This is the mail archive of the
ecos-patches@sources.redhat.com
mailing list for the eCos project.
kernel doc: fix timed* functions
- From: Jonathan Larmour <jlarmour at jifvik dot org>
- To: ecos-patches at sources dot redhat dot com
- Date: Wed, 2 Jul 2003 04:38:13 +0100
- Subject: 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