Misc clean-up and bugfixes related to multi-thread group signalling

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@5614 42af7a65-404d-4744-a932-0658087f49c3

4 files changed, 49 insertions, 16 deletions

diff --git a/nuttx/Documentation/NuttxUserGuide.html b/nuttx/Documentation/NuttxUserGuide.html
index 3aeb30788..34e6fe442 100644
--- a/nuttx/Documentation/NuttxUserGuide.html
+++ b/nuttx/Documentation/NuttxUserGuide.html
@@ -13,7 +13,7 @@
       <h1><big><font color="#3c34ec"><i>NuttX Operating System<p>User's Manual</i></font></big></h1>
       <p><small>by</small></p>
       <p>Gregory Nutt<p>
-      <p>Last Updated: February 4, 2013</p>
+      <p>Last Updated: February 5, 2013</p>
     </td>
   </tr>
 </table>
@@ -4629,26 +4629,61 @@ interface of the same name.
 </table>
 
 <p>
-  NuttX provides signal interfaces for tasks. Signals are used to
-  alter the flow control of tasks by communicating asynchronous events
-  within or between task contexts.
-  Any task or interrupt handler can post (or send) a signal to a particular task.
-  The task being signaled will execute task-specified signal handler
-  function the next time that the task has priority.
-  The signal handler is a user-supplied function that is bound to
-  a specific signal and performs whatever actions are necessary
-  whenever the signal is received.
+  <b>Tasks and Signals</b>.
+  NuttX provides signal interfaces for tasks and pthreads.
+  Signals are used toalter the flow control of tasks by communicating asynchronous events within or between task contexts.
+  Any task or interrupt handler can post (or send) a signal to a particular task using its task ID.
+  The task being signaled will execute task-specified signal handler function the next time that the task has priority.
+  The signal handler is a user-supplied function that is bound to a specific signal and performs whatever actions are necessary whenever the signal is received.
 </p>
 <p>
   There are no predefined actions for any signal.
-  The default action for all signals (i.e., when no signal handler has
-  been supplied by the user) is to ignore the signal.
+  The default action for all signals (i.e., when no signal handler has been supplied by the user) is to ignore the signal.
   In this sense, all NuttX are <i>real time</i> signals.
 </p>
 <p>
   Tasks may also suspend themselves and wait until a signal is received.
 </p>
 <p>
+  <b>Tasks Groups</b>.
+  NuttX supports both tasks and pthreads.
+  The primary difference between tasks and pthreads is the tasks are much more independent.
+  Tasks can create pthreads and those pthreads will share the resources of the task.
+  The main task and its children pthreads together are referred as a "task group."
+  A task group is used in NuttX to emulate a POSIX <i>process</i>.
+</p>
+<p>
+  See the <a href="http://www.nuttx.org/doku.php?id=wiki:nxinternal:nxtasking">NuttX Threading Wiki</a> page and the <a href="http://www.nuttx.org/doku.php?id=wiki:nxinternal:tasksnthreads">Tasks vs. Threads FAQ</a> for additional information on tasks and threads in NuttX.
+</p>
+<p>
+  <b>Signalling Multi-threaded Task Groups</b>.
+  The behavior of signals in the multi-thread task group is complex.
+  NuttX emulates a process model with task groups and follows the POSIX rules for signalling behavior.
+  Normally when you signal the task group you would signal using the task ID of the main task that created the group (in practice, a different task should not know the IDs of the internal threads created within the task group); that ID is remembered by the task group (even if the main task thread exits).
+</p>
+<p>
+  Here are some of the things that should happen when you signal a multi-threaded task group:
+</p>
+<ul>
+  <li>
+    If a task group receives a signal then one and only one indeterminate thread in the task group which is not blocking the signal will receive the signal.
+  </li>
+  <li>
+    If a task group receives a signal and more than one thread is waiting on that signal, then one and only one indeterminate thread out of that waiting group will receive the signal.
+  </li>
+</ul>
+<p>
+  You can mask out that signal using ''sigprocmask()'' (or ''pthread_sigmask()'').
+  That signal will then be effectively disabled and will never be received in those threads that have the signal masked.
+  On creation of a new thread, the new thread will inherit the signal mask of the parent thread that created it.
+  So you if block signal signals on one thread then create new threads, those signals will also be blocked in the new threads as well.
+</p>
+<p>
+  You can control which thread receives the signal by controlling the signal mask.
+  You should, for example, be able to create a separate thread whose sole purpose it is to catch a particular signal and respond to it.  Simply block the thread in the main task; then the signal will be blocked in all of the pthreads in the group too.  In the one "signal processing" pthread, enable the blocked signal. This thread will then be only thread that will receive the signal.
+</p>
+<p>
+  <b>Signal Interfaces</b>.
   The following signal handling interfaces are provided by NuttX:
 </p>
 <ul>
diff --git a/nuttx/sched/group_find.c b/nuttx/sched/group_find.c
index d7e82d1f9..4c1205bea 100644
--- a/nuttx/sched/group_find.c
+++ b/nuttx/sched/group_find.c
@@ -145,7 +145,7 @@ FAR struct task_group_s *group_findbygid(gid_t gid)
  *
  *****************************************************************************/
 
-#if !defined(CONFIG_DISABLE_PTHREAD) && defined(CONFIG_SCHED_HAVE_PARENT)
+#ifdef HAVE_GROUP_MEMBERS
 FAR struct task_group_s *group_findbypid(pid_t pid)
 {
   FAR struct task_group_s *group;
diff --git a/nuttx/sched/group_internal.h b/nuttx/sched/group_internal.h
index 520a9544b..f97f07d95 100644
--- a/nuttx/sched/group_internal.h
+++ b/nuttx/sched/group_internal.h
@@ -86,8 +86,6 @@ void group_leave(FAR struct tcb_s *tcb);
 
 #ifdef HAVE_GROUP_MEMBERS
 FAR struct task_group_s *group_findbygid(gid_t gid);
-#endif
-#if !defined(CONFIG_DISABLE_PTHREAD) && defined(CONFIG_SCHED_HAVE_PARENT)
 FAR struct task_group_s *group_findbypid(pid_t pid);
 #endif
 
diff --git a/nuttx/sched/task_exithook.c b/nuttx/sched/task_exithook.c
index 444bfee9c..5633786aa 100644
--- a/nuttx/sched/task_exithook.c
+++ b/nuttx/sched/task_exithook.c
@@ -396,7 +396,7 @@ static inline void task_sigchild(FAR struct tcb_s *ptcb,
       info.si_code            = CLD_EXITED;
       info.si_value.sival_ptr = NULL;
 #ifndef CONFIG_DISABLE_PTHREAD
-      info.si_pid             = chgrp->tg_task;
+      info.si_pid             = ctcb->group->tg_task;
 #else
       info.si_pid             = ctcb->pid;
 #endif