This is the mail archive of the ecos-patches@sources.redhat.com mailing list for the eCos project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

kernel doc: fix timed* functions


Index: ChangeLog
===================================================================
RCS file: /cvs/ecos/ecos/packages/kernel/current/ChangeLog,v
retrieving revision 1.105
diff -u -5 -p -r1.105 ChangeLog
--- ChangeLog	1 Jul 2003 17:34:53 -0000	1.105
+++ ChangeLog	2 Jul 2003 03:38:06 -0000
@@ -1,5 +1,11 @@
+2003-07-02  Jonathan Larmour  <jifl@eCosCentric.com>
+
+	* doc/kernel.sgml: Document that timeouts for timed functions are
+	absolute, not relative. Also document new semantics for
+	cyg_semaphore_timed_wait() for timeouts in the past.
+
 2003-07-01  Nick Garnett  <nickg@balti.calivar.com>
 
 	* include/clock.hxx: Made Cyg_Counter::add_alarm() and
 	Cyg_Counter::rem_alarm() private functions. They no longer lock
 	the scheduler, so should not be called directly, only via the
Index: doc/kernel.sgml
===================================================================
RCS file: /cvs/ecos/ecos/packages/kernel/current/doc/kernel.sgml,v
retrieving revision 1.6
diff -u -5 -p -r1.6 kernel.sgml
--- doc/kernel.sgml	22 Jan 2003 06:38:59 -0000	1.6
+++ doc/kernel.sgml	2 Jul 2003 03:38:10 -0000
@@ -3195,14 +3195,21 @@ locked the mutex that was specified in t
 <function>cyg_cond_init</function> call. This mutex will be unlocked
 and the current thread will be suspended in an atomic operation. When
 some other thread performs a signal or broadcast operation the current
 thread will be woken up and automatically reclaim ownership of the mutex
 again, allowing it to examine global state and determine whether or
-not the condition is now satisfied. The kernel supplies a variant of
-this function, <function>cyg_cond_timed_wait</function>, which can be
-used to wait on the condition variable or until some number of clock
-ticks have occurred. The mutex will always be reclaimed before
+not the condition is now satisfied.
+      </para>
+      <para>
+The kernel supplies a variant of this function,
+<function>cyg_cond_timed_wait</function>, which can be used to wait on
+the condition variable or until some number of clock ticks have
+occurred. The number of ticks is specified as an absolute, not
+relative tick count, and so in order to wait for a relative number of
+ticks, the return value of the <function>cyg_current_time()</function>
+function should be added to determine the absolute number of ticks.
+The mutex will always be reclaimed before
 <function>cyg_cond_timed_wait</function> returns, regardless of
 whether it was a result of a signal operation or a timeout.
       </para>
       <para>
 There is no <function>cyg_cond_trywait</function> function because
@@ -3378,18 +3385,25 @@ and <function>cyg_semaphore_wait</functi
       </para>
       <para>
 <function>cyg_semaphore_timed_wait</function> is a variant of
 <function>cyg_semaphore_wait</function>. It can be used to wait until
 either an event has occurred or a number of clock ticks have happened.
-The function returns success if the semaphore wait operation
-succeeded, or false if the operation timed out or was aborted by
-<function>cyg_thread_release</function>. If support for the real-time
+The number of ticks is specified as an absolute, not relative tick
+count, and so in order to wait for a relative number of ticks, the
+return value of the <function>cyg_current_time()</function> function
+should be added to determine the absolute number of ticks. The
+function returns success if the semaphore wait operation succeeded, or
+false if the operation timed out or was aborted by
+<function>cyg_thread_release</function>.
+If support for the real-time
 clock has been removed from the current configuration then this
 function will not be available.
 <function>cyg_semaphore_trywait</function> is another variant which
 will always return immediately rather than block, again returning
-success or failure.
+success or failure. If <function>cyg_semaphore_timedwait</function>
+is given a timeout in the past, it operates like
+<function>cyg_semaphore_trywait</function>.
       </para>
       <para>
 <function>cyg_semaphore_peek</function> can be used to get hold of the
 current counter value. This function is rarely useful except for
 debugging purposes since the counter value may change at any time if
@@ -3547,11 +3561,15 @@ with different priorities.
       </para>
       <para>
 There are two variants of <function>cyg_mbox_get</function>. The
 first, <function>cyg_mbox_timed_get</function> will wait until either
 a message is available or until a number of clock ticks have occurred.
-If no message is posted within the timeout then a null pointer will be
+The number of ticks is specified as an absolute, not relative tick
+count, and so in order to wait for a relative number of ticks, the
+return value of the <function>cyg_current_time()</function> function
+should be added to determine the absolute number of ticks.  If no
+message is posted within the timeout then a null pointer will be
 returned. <function>cyg_mbox_tryget</function> is a non-blocking
 operation which will either return a message if one is available or a
 null pointer.
       </para>
       <para>
@@ -3564,14 +3582,15 @@ if there is a waiting thread it will be 
 receive the message. If the mail box is currently full then
 <function>cyg_mbox_put</function> will block until there has been a
 get operation and a slot is available. The
 <function>cyg_mbox_timed_put</function> variant imposes a time limit
 on the put operation, returning false if the operation cannot be
-completed within the specified number of clock ticks. The
-<function>cyg_mbox_tryput</function> variant is non-blocking,
-returning false if there are no free slots available and the message
-cannot be posted without blocking.
+completed within the specified number of clock ticks and as for
+<function>cyg_mbox_timed_get</function> this is an absolute tick
+count. The <function>cyg_mbox_tryput</function> variant is
+non-blocking, returning false if there are no free slots available and
+the message cannot be posted without blocking.
       </para>
       <para>
 There are a further four functions available for examining the current
 state of a mailbox. The results of these functions must be used with
 care because usually the state can change at any time as a result of
@@ -3771,14 +3790,19 @@ that is currently in a wait operation, t
       </para>
       <para>
 <function>cyg_flag_timed_wait</function> is a variant of
 <function>cyg_flag_wait</function> which adds a timeout: the wait
 operation must succeed within the specified number of ticks, or it
-will fail with a return value of 0. <function>cyg_flag_poll</function>
-is a non-blocking variant: if the wait operation can succeed
-immediately it acts like <function>cyg_flag_wait</function>, otherwise
-it returns immediately with a value of 0.
+will fail with a return value of 0. The number of ticks is specified
+as an absolute, not relative tick count, and so in order to wait for a
+relative number of ticks, the return value of the
+<function>cyg_current_time()</function> function should be added to
+determine the absolute number of ticks.
+<function>cyg_flag_poll</function> is a non-blocking variant: if the
+wait operation can succeed immediately it acts like
+<function>cyg_flag_wait</function>, otherwise it returns immediately
+with a value of 0.
       </para>
       <para>
 <function>cyg_flag_setbits</function> is called by a producer thread
 or from inside a DSR when an event occurs. The specified bits are or'd
 into the current event flag value. This may cause a waiting thread to


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]