Last Updated: January 13, 2013
+Last Updated: January 23, 2013
@@ -4481,11 +4481,73 @@ build instrumentation is selected. Set to zero to disable.CONFIG_SCHED_HAVE_PARENT: Remember the ID of the parent thread when a new child thread is created.
+ CONFIG_SCHED_HAVE_PARENT: Remember the ID of the parent thread when a new child task is created.
This support enables some additional features (such as SIGCHLD) and modifies the behavior of other interfaces.
For example, it makes waitpid() more standards complete by restricting the waited-for tasks to the children of the caller.
Default: disabled.
CONFIG_SCHED_CHILD_STATUS: If this option is selected, then the exit status of the child task will be retained after the child task exits.
+ This option should be selected if you require knowledge of a child process' exit status.
+ Without this setting, wait(), waitpid() or waitid() may fail.
+ For example, if you do:
+ wait(), waitpid() or waitid()).
+
+ This can fail because the child task may run to completion before the wait begins.
+ There is a non-standard work-around in this case:
+ The above sequence will work if you disable pre-emption using sched_lock() prior to starting the child task, then re-enable pre-emption with sched_unlock() after the wait completes.
+ This works because the child task is not permitted to run until the wait is in place.
+
+ The standard solution would be to enable CONFIG_SCHED_CHILD_STATUS.
+ In this case the exit status of the child task is retained after the child exits and the wait will successful obtain the child task's exit status whether it is called before the child task exits or not.
+
+ Warning:
+ If you enable this feature, then your application must either (1) take responsibility for reaping the child status with wait(), waitpid() or waitid(), or (2) suppress retention of child status.
+ If you do not reap the child status, then you have a memory leak and your system will eventually fail.
+
+struct sigaction sa; + +sa.sa_handler = SIG_IGN; +sa.sa_flags = SA_NOCLDWAIT; +int ret = sigaction(SIGCHLD, &sa, NULL); ++
CONFIG_PREALLOC_CHILDSTATUS: To prevent runaway child status allocations and to improve
+ allocation performance, child task exit status structures are pre-allocated when the system boots.
+ This setting determines the number of child status structures that will be pre-allocated.
+ If this setting is not defined or if it is defined to be zero then a value of 2*MAX_TASKS is used.
+
+ Note that there cannot be more that CONFIG_MAX_TASKS tasks in total.
+ However, the number of child status structures may need to be significantly larger because this number includes the maximum number of tasks that are running PLUS the number of tasks that have exit'ed without having their exit status reaped (via wait(), waitpid() or waitid()).
+
+ Obviously, if tasks spawn children indefinitely and never have the exit status reaped, then you may have a memory leak!
+ If you enable the SCHED_CHILD_STATUS feature, then your application must take responsibility for either (1) reaping the child status with wait(), waitpid() or waitid() or it must (2) suppress retention of child status. Otherwise, your system will eventually fail.
+
+ Retention of child status can be suppressed on the parent using logic like: +
++struct sigaction sa; + +sa.sa_handler = SIG_IGN; +sa.sa_flags = SA_NOCLDWAIT; +int ret = sigaction(SIGCHLD, &sa, NULL); ++
CONFIG_SYSTEM_TIME16:
The range of system time is, by default, 32-bits.
diff --git a/Documentation/NuttxUserGuide.html b/Documentation/NuttxUserGuide.html
index 3cfb63f11e..10e5eb7ba4 100644
--- a/Documentation/NuttxUserGuide.html
+++ b/Documentation/NuttxUserGuide.html
@@ -13,7 +13,7 @@
User's Manual
by
Gregory Nutt
-
Last Updated: January 13, 2013
+Last Updated: January 23, 2013
@@ -1767,20 +1767,114 @@ priority of the calling task is returned. -Scheduler locking interfaces
++ Task Control Interfaces. +
+ Scheduler locking interfaces. + This non-standard interfaces are used to enable and disable pre-emption and to test is pre-emption is currently enabled. +
+ +
+ Task synchronization interfaces.
+ wait(), waitpid() or waitid() may be used to wait for termination of child tasks.
+
+ atexit() and on_exit() may be use to register callback functions that are executed when a task exits.
+
Task synchronization interfaces
+ ++ Parent and Child Tasks. + The task synchronization interfaces historically depend upon parent and child relationships between tasks. + But default, NuttX does not use any parent/child knowledge. + However, there are three important configuration options that can change that. +
+ CONFIG_SCHED_HAVE_PARENT.
+ If this setting is defined, then it instructs NuttX to remember the task ID of the parent task when each new child task is created.
+ This support enables some additional features (such as SIGCHLD) and modifies the behavior of other interfaces.
+ For example, it makes waitpid() more standards complete by restricting the waited-for tasks to the children of the caller.
+
+ CONFIG_SCHED_CHILD_STATUS
+ If this option is selected, then the exit status of the child task will be retained after the child task exits.
+ This option should be selected if you require knowledge of a child process' exit status.
+ Without this setting, wait(), waitpid() or waitid() may fail.
+ For example, if you do:
+
wait(), waitpid() or waitid()).
+
+ This may fail because the child task may run to completion before the wait begins.
+ There is a non-standard work-around in this case:
+ The above sequence will work if you disable pre-emption using sched_lock() prior to starting the child task, then re-enable pre-emption with sched_unlock() after the wait completes.
+ This works because the child task is not permitted to run until the wait is in place.
+
+ The standard solution would be to enable CONFIG_SCHED_CHILD_STATUS.
+ In this case the exit status of the child task is retained after the child exits and the wait will successful obtain the child task's exit status whether it is called before the child task exits or not.
+
+ CONFIG_PREALLOC_CHILDSTATUS.
+ To prevent runaway child status allocations and to improve allocation performance, child task exit status structures are pre-allocated when the system boots.
+ This setting determines the number of child status structures that will be pre-allocated.
+ If this setting is not defined or if it is defined to be zero then a value of 2*MAX_TASKS is used.
+
+ Note that there cannot be more that CONFIG_MAX_TASKS tasks in total.
+ However, the number of child status structures may need to be significantly larger because this number includes the maximum number of tasks that are running PLUS the number of tasks that have exit'ed without having their exit status reaped (via wait(), waitpid() or waitid()).
+
+ Obviously, if tasks spawn children indefinitely and never have the exit status reaped, then you may have a memory leak! + (See Warning below) +
+
+ Warning:
+ If you enable the CONFIG_SCHED_CHILD_STATUS feature, then your application must either (1) take responsibility for reaping the child status with wait(), waitpid() or waitid(), or (2) suppress retention of child status.
+ If you do not reap the child status, then you have a memory leak and your system will eventually fail.
+
+struct sigaction sa; + +sa.sa_handler = SIG_IGN; +sa.sa_flags = SA_NOCLDWAIT; +int ret = sigaction(SIGCHLD, &sa, NULL); +
SIG_DFL is treated like SIG_IGN.
+ sa_flags in struct sigaction of act input are ignored (all treated like SA_SIGINFO).
+ The one exception is if CONFIG_SCHED_CHILDSTATUS is defined;
+ then SA_NOCLDWAIT is supported but only for SIGCHLD.
+