vxwsem.html

来自「vxworks相关论文」· HTML 代码 · 共 749 行 · 第 1/3 页

<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
OK, or ERROR if the operation is not supported.
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWSem.html#top">VXWSem</a></b>, <b><i>VXWCSem::VXWCsem</i>(&nbsp;)</b>, <b><i>VXWBSem::VXWBsem</i>(&nbsp;)</b>, <b><i>VXWMSem::VXWMsem</i>(&nbsp;)</b>,  
<i>VxWorks Programmer's Guide: Basic OS</i>

<hr>
<a name="VXWSem::id"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWSem::id</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWSem::id</i>(&nbsp;)</strong> - reveal underlying semaphore ID</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>    SEM_ID id ()</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine returns the semaphore ID corresponding to a semaphore
object.  The semaphore ID is used by the C interface to VxWorks
semaphores.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
Semaphore ID.
<p>
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWSem.html#top">VXWSem</a></b>, <b><a href="./semLib.html#top">semLib</a></b>

<hr>
<a name="VXWSem::info"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWSem::info</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWSem::info</i>(&nbsp;)</strong> - get a list of task IDs that are blocked on a semaphore</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS info
    (
    int idList[],
    int maxTasks
    ) const</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine reports the tasks blocked on a specified semaphore.
Up to <i>maxTasks</i> task IDs are copied to the array specified by <i>idList</i>.
The array is unordered.
<p>
</blockquote><h4>WARNING</h4><blockquote><p>
<p>
There is no guarantee that all listed tasks are still valid or that new
tasks have not been blocked by the time <b><i><a href="./VXWSem.html#VXWSem::info">VXWSem::info</a></i>(&nbsp;)</b> returns.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
The number of blocked tasks placed in <i>idList</i>.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWSem.html#top">VXWSem</a></b>

<hr>
<a name="VXWSem::show"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWSem::show</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWSem::show</i>(&nbsp;)</strong> - show information about a semaphore</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>STATUS show
    (
    int level
    ) const</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine displays (on standard output) the state and optionally
the pended tasks of a semaphore.
<p>
A summary of the state of the semaphore is displayed as follows:
<pre>    Semaphore Id        : 0x585f2
    Semaphore Type      : BINARY
    Task Queuing        : PRIORITY
    Pended Tasks        : 1
    State               : EMPTY {Count if COUNTING, Owner if MUTEX}
</pre>

If <i>level</i> is 1, more detailed information is displayed.
If tasks are blocked on the queue, they are displayed in the order
in which they will unblock, as follows:
<pre>       NAME      TID    PRI DELAY
    ---------- -------- --- -----
    tExcTask    3fd678   0    21
    tLogTask    3f8ac0   0   611
</pre>

</blockquote><h4>RETURNS</h4><blockquote><p>
OK or ERROR.
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWSem.html#top">VXWSem</a></b>

<hr>
<a name="VXWCSem::VXWCSem"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWCSem::VXWCSem</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWCSem::VXWCSem</i>(&nbsp;)</strong> - create and initialize a counting semaphore</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>VXWCSem
    (
    int opts,
    int count
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine allocates and initializes a counting semaphore.  The
semaphore is initialized to the specified initial count.
<p>
The <i>opts</i> parameter specifies the queuing style for blocked tasks.
Tasks may be queued on a priority basis or a first-in-first-out basis.
These options are <b>SEM_Q_PRIORITY</b> and <b>SEM_Q_FIFO</b>, respectively.
<p>
A counting semaphore may be viewed as a cell in memory whose contents
keep track of a count.  When a task takes a counting semaphore, using
<b><i><a href="./VXWSem.html#VXWSem::take">VXWSem::take</a></i>(&nbsp;)</b>, subsequent action depends on the state of the count:
<dl>
<dt>
(1)
<dd>

If the count is non-zero, it is decremented and the calling task
continues executing.
<p>
<dt>
(2)
<dd>
 If the count is zero, the task is blocked, pending the availability
of the semaphore.  If a timeout is specified and the timeout expires, the
pended task is removed from the queue of pended tasks and enters the
ready state with an ERROR status.  A pended task is ineligible for CPU
allocation.  Any number of tasks may be pended simultaneously on the same
counting semaphore. 
</dl>

<p>
When a task gives a semaphore, using <b><i><a href="./VXWSem.html#VXWSem::give">VXWSem::give</a></i>(&nbsp;)</b>, the next
available task in the pend queue is unblocked.  If no task is
pending on this semaphore, the semaphore count is incremented.
Note that if a semaphore is given, and a task is unblocked that is
of higher priority than the task that called <b><i><a href="./VXWSem.html#VXWSem::give">VXWSem::give</a></i>(&nbsp;)</b>, the
unblocked task preempts the calling task. 
<p>
A <b><i><a href="./VXWSem.html#VXWSem::flush">VXWSem::flush</a></i>(&nbsp;)</b> on a counting semaphore atomically unblocks all pended
tasks in the semaphore queue.  Thus, all tasks are made ready before any
task actually executes.  The count of the semaphore remains unchanged.
<p>
</blockquote><h4>INTERRUPT USAGE</h4><blockquote><p>
Counting semaphores may be given but not taken from interrupt level.
<p>
</blockquote><h4>CAVEATS</h4><blockquote><p>
There is no mechanism to give back or reclaim semaphores automatically when
tasks are suspended or deleted.  Such a mechanism, though desirable, is not
currently feasible.  Without explicit knowledge of the state of the guarded
resource or region, reckless automatic reclamation of a semaphore could
leave the resource in a partial state.  Thus, if a task ceases execution
unexpectedly, as with a bus error, currently owned semaphores are not 
given back, effectively leaving a resource permanently unavailable.  The
mutual-exclusion semaphores provided by <b>VXWMSem</b> offer protection from
unexpected task deletion.
<p>
</blockquote><h4>RETURNS</h4><blockquote><p>
N/A
</blockquote><h4>SEE ALSO</h4><blockquote><p>
<b><a href="./VXWSem.html#top">VXWSem</a></b>

<hr>
<a name="VXWBSem::VXWBSem"></a>
<p align=right>
<a href="rtnIndex.html"><i>Wind Foundation Classes :  Methods</i></a></p>

</blockquote><h1><i>VXWBSem::VXWBSem</i>(&nbsp;)</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote>  
<p><strong><i>VXWBSem::VXWBSem</i>(&nbsp;)</strong> - create and initialize a binary semaphore</p>

</blockquote><h4>SYNOPSIS</h4><blockquote><p>
<pre>VXWBSem
    (
    int         opts,
    SEM_B_STATE iState
    )</pre>

</blockquote><h4>DESCRIPTION</h4><blockquote><p>
This routine allocates and initializes a binary semaphore.  The
semaphore is initialized to the state <i>iState</i>:  either <b>SEM_FULL</b>
(1) or <b>SEM_EMPTY</b> (0).
<p>
The <i>opts</i> parameter specifies the queuing style for blocked tasks.
Tasks can be queued on a priority basis or a first-in-first-out basis.
These options are <b>SEM_Q_PRIORITY</b> and <b>SEM_Q_FIFO</b>, respectively.
<p>
Binary semaphores are the most versatile, efficient, and conceptually
simple type of semaphore.  They can be used to: (1) control mutually
exclusive access to shared devices or data structures, or (2) synchronize
multiple tasks, or task-level and interrupt-level processes.  Binary
semaphores form the foundation of numerous VxWorks facilities.
<p>
A binary semaphore can be viewed as a cell in memory whose contents
are in one of two states, full or empty.  When a task takes a
binary semaphore, using <b><i><a href="./VXWSem.html#VXWSem::take">VXWSem::take</a></i>(&nbsp;)</b>, subsequent action depends
on the state of the semaphore:
<dl>
<dt>
(1)
<dd>

If the semaphore is full, the semaphore is made empty, and the calling task
continues executing.
<p>
<dt>
(2)
<dd>
 If the semaphore is empty, the task is blocked, pending the
availability of the semaphore.  If a timeout is specified and the timeout
expires, the pended task is removed from the queue of pended tasks
and enters the ready state with an ERROR status.  A pended task
is ineligible for CPU allocation.  Any number of tasks may be pended
simultaneously on the same binary semaphore. 
</dl>

<p>
When a task gives a binary semaphore, using <b><i><a href="./VXWSem.html#VXWSem::give">VXWSem::give</a></i>(&nbsp;)</b>, the
next available task in the pend queue is unblocked.  If no task is
pending on this semaphore, the semaphore becomes full.  Note that
if a semaphore is given, and a task is unblocked that is of higher
priority than the task that called <b><i><a href="./VXWSem.html#VXWSem::give">VXWSem::give</a></i>(&nbsp;)</b>, the unblocked
task preempts the calling task.
<p>
</blockquote><h4>MUTUAL EXCLUSION</h4><blockquote><p>
To use a binary semaphore as a means of mutual exclusion, first create it
with an initial state of full.
<p>
Then guard a critical section or resource by taking the semaphore with
<b><i><a href="./VXWSem.html#VXWSem::take">VXWSem::take</a></i>(&nbsp;)</b>, and exit the section or release the resource by giving
the semaphore with <b><i><a href="./VXWSem.html#VXWSem::give">VXWSem::give</a></i>(&nbsp;)</b>.
<p>
While there is no restriction on the same semaphore being given,
taken, or flushed by multiple tasks, it is important to ensure the
proper functionality of the mutual-exclusion construct.  While
there is no danger in any number of processes taking a semaphore,
the giving of a semaphore should be more carefully controlled.  If