+++ /dev/null
-<!-- Copyright (C) 2003 Red Hat, Inc. -->
-<!-- This material may be distributed only subject to the terms -->
-<!-- and conditions set forth in the Open Publication License, v1.0 -->
-<!-- or later (the latest version is presently available at -->
-<!-- http://www.opencontent.org/openpub/). -->
-<!-- Distribution of the work or derivative of the work in any -->
-<!-- standard (paper) book form is prohibited unless prior -->
-<!-- permission is obtained from the copyright holder. -->
-<HTML
-><HEAD
-><TITLE
->Thread control</TITLE
-><meta name="MSSmartTagsPreventParsing" content="TRUE">
-<META
-NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
-REL="HOME"
-TITLE="eCos Reference Manual"
-HREF="ecos-ref.html"><LINK
-REL="UP"
-TITLE="The eCos Kernel"
-HREF="kernel.html"><LINK
-REL="PREVIOUS"
-TITLE="Thread information"
-HREF="kernel-thread-info.html"><LINK
-REL="NEXT"
-TITLE="Thread termination"
-HREF="kernel-thread-termination.html"></HEAD
-><BODY
-CLASS="REFENTRY"
-BGCOLOR="#FFFFFF"
-TEXT="#000000"
-LINK="#0000FF"
-VLINK="#840084"
-ALINK="#0000FF"
-><DIV
-CLASS="NAVHEADER"
-><TABLE
-SUMMARY="Header navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TH
-COLSPAN="3"
-ALIGN="center"
->eCos Reference Manual</TH
-></TR
-><TR
-><TD
-WIDTH="10%"
-ALIGN="left"
-VALIGN="bottom"
-><A
-HREF="kernel-thread-info.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="80%"
-ALIGN="center"
-VALIGN="bottom"
-></TD
-><TD
-WIDTH="10%"
-ALIGN="right"
-VALIGN="bottom"
-><A
-HREF="kernel-thread-termination.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-></TABLE
-><HR
-ALIGN="LEFT"
-WIDTH="100%"></DIV
-><H1
-><A
-NAME="KERNEL-THREAD-CONTROL">Thread control</H1
-><DIV
-CLASS="REFNAMEDIV"
-><A
-NAME="AEN482"
-></A
-><H2
->Name</H2
->cyg_thread_yield, cyg_thread_delay, cyg_thread_suspend, cyg_thread_resume, cyg_thread_release -- Control whether or not a thread is running</DIV
-><DIV
-CLASS="REFSYNOPSISDIV"
-><A
-NAME="AEN489"><H2
->Synopsis</H2
-><DIV
-CLASS="FUNCSYNOPSIS"
-><A
-NAME="AEN490"><P
-></P
-><TABLE
-BORDER="5"
-BGCOLOR="#E0E0F0"
-WIDTH="70%"
-><TR
-><TD
-><PRE
-CLASS="FUNCSYNOPSISINFO"
->#include <cyg/kernel/kapi.h>
- </PRE
-></TD
-></TR
-></TABLE
-><P
-><CODE
-><CODE
-CLASS="FUNCDEF"
->void cyg_thread_yield</CODE
->(void);</CODE
-></P
-><P
-><CODE
-><CODE
-CLASS="FUNCDEF"
->void cyg_thread_delay</CODE
->(cyg_tick_count_t delay);</CODE
-></P
-><P
-><CODE
-><CODE
-CLASS="FUNCDEF"
->void cyg_thread_suspend</CODE
->(cyg_handle_t thread);</CODE
-></P
-><P
-><CODE
-><CODE
-CLASS="FUNCDEF"
->void cyg_thread_resume</CODE
->(cyg_handle_t thread);</CODE
-></P
-><P
-><CODE
-><CODE
-CLASS="FUNCDEF"
->void cyg_thread_release</CODE
->(cyg_handle_t thread);</CODE
-></P
-><P
-></P
-></DIV
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN516"
-></A
-><H2
->Description</H2
-><P
->These functions provide some control over whether or not a particular
-thread can run. Apart from the required use of
-<TT
-CLASS="FUNCTION"
->cyg_thread_resume</TT
-> to start a newly-created
-thread, application code should normally use proper synchronization
-primitives such as condition variables or mail boxes.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN520"
-></A
-><H2
->Yield</H2
-><P
-><TT
-CLASS="FUNCTION"
->cyg_thread_yield</TT
-> allows a thread to relinquish
-control of the processor to some other runnable thread which has the
-same priority. This can have no effect on any higher-priority thread
-since, if such a thread were runnable, the current thread would have
-been preempted in its favour. Similarly it can have no effect on any
-lower-priority thread because the current thread will always be run in
-preference to those. As a consequence this function is only useful
-in configurations with a scheduler that allows multiple threads to run
-at the same priority, for example the mlqueue scheduler. If instead
-the bitmap scheduler was being used then
-<TT
-CLASS="FUNCTION"
->cyg_thread_yield()</TT
-> would serve no purpose.
- </P
-><P
->Even if a suitable scheduler such as the mlqueue scheduler has been
-configured, <TT
-CLASS="FUNCTION"
->cyg_thread_yield</TT
-> will still rarely
-prove useful: instead timeslicing will be used to ensure that all
-threads of a given priority get a fair slice of the available
-processor time. However it is possible to disable timeslicing via the
-configuration option <TT
-CLASS="VARNAME"
->CYGSEM_KERNEL_SCHED_TIMESLICE</TT
->,
-in which case <TT
-CLASS="FUNCTION"
->cyg_thread_yield</TT
-> can be used to
-implement a form of cooperative multitasking.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN529"
-></A
-><H2
->Delay</H2
-><P
-><TT
-CLASS="FUNCTION"
->cyg_thread_delay</TT
-> allows a thread to suspend until
-the specified number of clock ticks have occurred. For example, if a
-value of 1 is used and the system clock runs at a frequency of 100Hz
-then the thread will sleep for up to 10 milliseconds. This
-functionality depends on the presence of a real-time system clock, as
-controlled by the configuration option
-<TT
-CLASS="VARNAME"
->CYGVAR_KERNEL_COUNTERS_CLOCK</TT
->.
- </P
-><P
->If the application requires delays measured in milliseconds or similar
-units rather than in clock ticks, some calculations are needed to
-convert between these units as described in <A
-HREF="kernel-clocks.html"
->Clocks</A
->. Usually these calculations can be done by
-the application developer, or at compile-time. Performing such
-calculations prior to every call to
-<TT
-CLASS="FUNCTION"
->cyg_thread_delay</TT
-> adds unnecessary overhead to the
-system.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN537"
-></A
-><H2
->Suspend and Resume</H2
-><P
->Associated with each thread is a suspend counter. When a thread is
-first created this counter is initialized to 1.
-<TT
-CLASS="FUNCTION"
->cyg_thread_suspend</TT
-> can be used to increment the
-suspend counter, and <TT
-CLASS="FUNCTION"
->cyg_thread_resume</TT
-> decrements
-it. The scheduler will never run a thread with a non-zero suspend
-counter. Therefore a newly created thread will not run until it has
-been resumed.
- </P
-><P
->An occasional problem with the use of suspend and resume functionality
-is that a thread gets suspended more times than it is resumed and
-hence never becomes runnable again. This can lead to very confusing
-behaviour. To help with debugging such problems the kernel provides a
-configuration option
-<TT
-CLASS="VARNAME"
->CYGNUM_KERNEL_MAX_SUSPEND_COUNT_ASSERT</TT
-> which
-imposes an upper bound on the number of suspend calls without matching
-resumes, with a reasonable default value. This functionality depends
-on infrastructure assertions being enabled.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="AEN544"
-></A
-><H2
->Releasing a Blocked Thread</H2
-><P
->When a thread is blocked on a synchronization primitive such as a
-semaphore or a mutex, or when it is waiting for an alarm to trigger,
-it can be forcibly woken up using
-<TT
-CLASS="FUNCTION"
->cyg_thread_release</TT
->. Typically this will call the
-affected synchronization primitive to return false, indicating that
-the operation was not completed successfully. This function has to be
-used with great care, and in particular it should only be used on
-threads that have been designed appropriately and check all return
-codes. If instead it were to be used on, say, an arbitrary thread that
-is attempting to claim a mutex then that thread might not bother to
-check the result of the mutex lock operation - usually there would be
-no reason to do so. Therefore the thread will now continue running in
-the false belief that it has successfully claimed a mutex lock, and
-the resulting behaviour is undefined. If the system has been built
-with assertions enabled then it is possible that an assertion will
-trigger when the thread tries to release the mutex it does not
-actually own.
- </P
-><P
->The main use of <TT
-CLASS="FUNCTION"
->cyg_thread_release</TT
-> is in the
-POSIX compatibility layer, where it is used in the implementation of
-per-thread signals and cancellation handlers.
- </P
-></DIV
-><DIV
-CLASS="REFSECT1"
-><A
-NAME="KERNEL-THREAD-CONTROL-CONTEXT"
-></A
-><H2
->Valid contexts</H2
-><P
-><TT
-CLASS="FUNCTION"
->cyg_thread_yield</TT
-> can only be called from thread
-context, A DSR must always run to completion and cannot yield the
-processor to some thread. <TT
-CLASS="FUNCTION"
->cyg_thread_suspend</TT
->,
-<TT
-CLASS="FUNCTION"
->cyg_thread_resume</TT
->, and
-<TT
-CLASS="FUNCTION"
->cyg_thread_release</TT
-> may be called from thread or
-DSR context.
- </P
-></DIV
-><DIV
-CLASS="NAVFOOTER"
-><HR
-ALIGN="LEFT"
-WIDTH="100%"><TABLE
-SUMMARY="Footer navigation table"
-WIDTH="100%"
-BORDER="0"
-CELLPADDING="0"
-CELLSPACING="0"
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
-><A
-HREF="kernel-thread-info.html"
-ACCESSKEY="P"
->Prev</A
-></TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="ecos-ref.html"
-ACCESSKEY="H"
->Home</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
-><A
-HREF="kernel-thread-termination.html"
-ACCESSKEY="N"
->Next</A
-></TD
-></TR
-><TR
-><TD
-WIDTH="33%"
-ALIGN="left"
-VALIGN="top"
->Thread information</TD
-><TD
-WIDTH="34%"
-ALIGN="center"
-VALIGN="top"
-><A
-HREF="kernel.html"
-ACCESSKEY="U"
->Up</A
-></TD
-><TD
-WIDTH="33%"
-ALIGN="right"
-VALIGN="top"
->Thread termination</TD
-></TR
-></TABLE
-></DIV
-></BODY
-></HTML
->
\ No newline at end of file
projects / karo-tx-redboot.git / blobdiff