cyg_thread_create | |
Name: | cyg_thread_create ( ) - create a new thread |
---|---|
Synopsis: | void cyg_thread_create ( cyg_addrword_t sched_info, /* scheduling info (priority) */ cyg_thread_entry_t *entry, /* thread entry point */ cyg_addrword_t entry_data, /* entry point argument */ char *name, /* name of thread */ void *stack_base, /* pointer to stack base */ cyg_ucount32 stack_size, /* size of stack in bytes */ cyg_handle_t *handle, /* returned thread handle */ cyg_thread *thread /* space to store thread data */ ) |
Description: | This creates a new thread. The ID of the thread is returned through "*handle". Since eCos does it's best to never use dynamic memory "*thread" is is used to store thread specific information. Once the thread is created it can be manipulated with "handle". One thing to note is that like Unix, the lower the priority value (i.e. sched_info) the higher the priority. A priority of 0 is the highest possible priority in the system and CYG_THREAD_MIN_PRIORITY is the lowest possible priority. It is a good idea not to run any thread at CYG_THREAD_MIN_PRIORITY since the idle thread runs at that priority. Priority values depend on the scheduler. Note that if you use the bitmap scheduler, two threads cannot share the same priority. Note that threads are created in a suspended state. Before the thread will run, you must call cyg_thread_resume. The entry function prototype is: void cyg_thread_entry(CYG_ADDRWORD data). |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing. |
See Also: | cyg_thread_exit, cyg_thread_delete, cyg_thread_kill, cyg_thread_set_priority, cyg_thread_add_destructor, cyg_thread_rem_destructor |
cyg_thread_exit | |
Name: | cyg_thread_exit ( ) - exit a thread |
---|---|
Synopsis: | void cyg_thread_exit ( void ) |
Description: | This stops the calling thread. Be sure that any resources that have been allocated by the thread have been freed before calling this function otherwise you risk deadlocking the system. This will cause any destructors associated with the thread to be called before the thread exits. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing - this function doesn't return |
See Also: | cyg_thread_create, cyg_thread_exit, cyg_thread_delete, cyg_thread_resume, cyg_thread_kill, cyg_thread_add_destructor, cyg_thread_rem_destructor |
cyg_thread_delete | |
Name: | cyg_thread_delete ( ) - delete a thread |
---|---|
Synopsis: | cyg_bool_t cyg_thread_delete ( cyg_handle_t thread /* thread to delete */ ) |
Description: | This deletes a thread. This is a dangerous function to call. If it's possible, send a message to the thread you want to delete and let itself shutdown with cyg_thread_exit. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | "true" is the thread was deleted, "false" otherwise. |
See Also: | cyg_thread_create, cyg_thread_exit, cyg_thread_kill, cyg_thread_release, cyg_thread_add_destructor, cyg_thread_rem_destructor |
cyg_thread_suspend | |
Name: | cyg_thread_suspend ( ) - suspend a thread |
---|---|
Synopsis: | void cyg_thread_suspend ( cyg_handle_t thread /* thread to suspend */ ) |
Description: | This suspends a thread. A thread can be suspended multiple times. For each call to cyg_thread_suspend, there must be a call to cyg_thread_resume to take the thread out of the suspended state. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_resume |
cyg_thread_resume | |
Name: | cyg_thread_resume ( ) - resume a suspended thread |
---|---|
Synopsis: | void cyg_thread_resume ( cyg_handle_t thread /* thread to resume from a suspended state */ ) |
Description: | This decrements the suspend count on a thread. If the suspend count goes to 0, the thread will be resumed and will then continue to run. If the thread was exited, this will reinitialize the thread. (? RBW: Will reinitializing thread cause the thread to reinitialize in a suspended state or a running state ? - need to test ) |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_suspend |
cyg_thread_kill | |
Name: | cyg_thread_kill ( ) - kill a thread |
---|---|
Synopsis: | void cyg_thread_kill ( cyg_handle_t thread /* thread to kill */ ) |
Description: | This will force another thread to exit and cause it to stop. This is dangerous to use because if the thread that is being killed has any resources allocated (memory, semaphores, mutexes, etc.) they will not be freed when the thread is killed. This can cause the system to deadlock. This will cause any destructors associated with the thread to be called before the thread is killed. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_create, cyg_thread_exit, cyg_thread_delete |
cyg_thread_release | |
Name: | cyg_thread_release ( ) - release a thread from a wait |
---|---|
Synopsis: | void cyg_thread_release ( cyg_handle_t thread /* thread to release */ ) |
Description: | This causes a thread that is in a wait to be broken out of it. It is the responsibility of the thread that was released to detect that it was broken out of it's wait. If you make use of this function, you will have to program defensively around any synchronization mechanism. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_delay |
cyg_thread_yield | |
Name: | cyg_thread_yield ( ) - yield the thread to another thread of equal priority |
---|---|
Synopsis: | void cyg_thread_yield ( void ) |
Description: | This yields control of the CPU to the next runnable thread of equal priority. If there is no other runnable thread of equal priority this will effectively do nothing. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_delay |
cyg_thread_self | |
Name: | cyg_thread_self ( ) - get calling thread's thread ID |
---|---|
Synopsis: | cyg_handle_t cyg_thread_self ( void ) |
Description: | This gets the thread ID of the calling thread. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the thread ID of the calling thread |
See Also: | cyg_thread_create |
cyg_thread_idle_thread | |
Name: | cyg_thread_idle_thread ( ) - get the idle thread's thread ID |
---|---|
Synopsis: | cyg_handle_t cyg_thread_idle_thread ( void ) |
Description: | This function gets the idle thread's thread ID. Be careful with modifying the idle thread's priority, or in general doing anything with it since it's not a standard thread. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the thread ID of the idle thread |
See Also: |
cyg_thread_set_priority | |
Name: | cyg_thread_set_priority ( ) - set the priority of a thread |
---|---|
Synopsis: | void cyg_thread_set_priority ( cyg_handle_t thread, /* thread ID */ cyg_priority_t priority /* new priority */ ) |
Description: | This changes the priority of the specified thread. Like Unix, the lower the value of the priority the higher the priority. A priority of 0 is the highest priority in the system. CYG_THREAD_MIN_PRIORITY is the lowest priority and it's value is dependent on the scheduler that you use. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_create, cyg_thread_get_priority, cyg_thread_get_current_priority |
cyg_thread_get_priority | |
Name: | cyg_thread_get_priority ( ) - get the priority of a thread |
---|---|
Synopsis: | cyg_priority_t cyg_thread_get_priority ( cyg_handle_t thread /* thread ID */ ) |
Description: | This returns the set priority of the given thread. If the priority of the thread has been modified by a mutex with a ceiling, priority inversion or some other similar mechanism this will not return the current priority, but the "normal" priority of the thread. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the set priority of the given thread |
See Also: | cyg_thread_create, cyg_thread_set_priority, cyg_thread_get_current_priority |
cyg_thread_get_current_priority | |
Name: | cyg_thread_get_current_priority ( ) - get current priority of a thread |
---|---|
Synopsis: | cyg_priority_t cyg_thread_get_current_priority ( cyg_handle_t thread /* thread ID */ ) |
Description: | This returns the current priority of the given thread. If the priority of the thread has been modified by a mutex with a ceiling, priority inversion or some other similar mechanism this will return the current priority, not the "normal" priority of the thread. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the current running priority of the given thread. |
See Also: | cyg_thread_create, cyg_thread_set_priority, cyg_thread_get_priority |
cyg_thread_delay | |
Name: | cyg_thread_delay ( ) - delay the calling thread for a number of ticks |
---|---|
Synopsis: | void cyg_thread_delay ( cyg_tick_count_t delay /* number of ticks to delay */ ) |
Description: | This delays a thread for an arbitrary number of ticks. The length of a tick is provided by the resolution of the system clock. ( RBW: provide more information on getting information on the real time clock ) |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_release |
cyg_thread_get_stack_base | |
Name: | cyg_thread_get_stack_base ( ) - get a thread's stack base address |
---|---|
Synopsis: | cyg_addrword_t cyg_thread_get_stack_base ( cyg_handle_t thread /* thread ID */ ) |
Description: | This returns the address of a given thread's stack. This may or may not be what was passed in the creation of the thread since debug capabilities and alignment requirements might modify it somewhat. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the base address of the thread's stack. |
See Also: | cyg_thread_create, cyg_thread_get_stack_size, cyg_thread_measure_stack_usage |
cyg_thread_get_stack_size | |
Name: | cyg_thread_get_stack_size ( ) - get a thread's stack size |
---|---|
Synopsis: | cyg_uint32 cyg_thread_get_stack_size ( cyg_handle_t thread /* thread ID */ ) |
Description: | This returns the size of a given thread's stack. This may or may not be what was passed in the creation of the thread since debug capabilities and alignment requirements might modify it somewhat. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the size in bytes of the thread's stack. |
See Also: | cyg_thread_create, cyg_thread_get_stack_base, cyg_thread_measure_stack_usage |
cyg_thread_measure_stack_usage | |
Name: | cyg_thread_measure_stack_usage ( ) - get a thread's current stack usage |
---|---|
Synopsis: | cyg_uint32 cyg_thread_measure_stack_usage ( cyg_handle_t thread /* thread ID */ ) |
Description: | This gets the number of bytes that have been used so far by the given thread. Note that if this function returns 0, it's likely you will overrun the stack in the future. This is essentially a debug function. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the number of bytes currently used by the given thread. |
See Also: | cyg_thread_create, cyg_thread_get_stack_base, cyg_thread_get_stack_size |
cyg_thread_new_data_index | |
Name: | cyg_thread_new_data_index ( ) - get a free data index for all threads |
---|---|
Synopsis: | cyg_ucount32 cyg_thread_new_data_index ( void ) |
Description: | This gets a new unused data index. The index allocated is useful for storing data that is specific to each thread. For example, the global variable "errno" may be allocated as a per thread data variable. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | a free data index or -1 if there were no more free indexes. |
See Also: | cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data |
cyg_thread_free_data_index | |
Name: | cyg_thread_free_data_index ( ) - free a data index for all threads |
---|---|
Synopsis: | void cyg_thread_free_data_index ( cyg_ucount32 index /* index to free */ ) |
Description: | This frees a data index and makes it available for use again by the system. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_new_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data |
cyg_thread_get_data | |
Name: | cyg_thread_get_data ( ) - read per thread data from a given index |
---|---|
Synopsis: | CYG_ADDRWORD cyg_thread_get_data ( cyg_ucount32 index /* index of per thread data */ ) |
Description: | Get per thread data. Be careful with this, giving a bad index will cause an ASSERT if you have it turned on, but no other error checking is performed otherwise. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | the per thread data stored at a specified index. |
See Also: | cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data_ptr, cyg_thread_set_data |
cyg_thread_get_data_ptr | |
Name: | cyg_thread_get_data_ptr ( ) - get a data pointer to per thread data |
---|---|
Synopsis: | CYG_ADDRWORD *cyg_thread_get_data_ptr ( cyg_ucount32 index /* index of per thread data */ ) |
Description: | Get a pointer to per thread data. You can use this function in lieu of cyg_thread_get_data or cyg_thread_set_data, and it's a little faster to use. The pointer, of course, is only valid in the context of the calling thread. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | a pointer to per thread data at the given index. |
See Also: | cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_set_data |
cyg_thread_set_data | |
Name: | cyg_thread_set_data ( ) - set per thread data at a given index |
---|---|
Synopsis: | void cyg_thread_set_data ( cyg_ucount32 index, /* index of per thread data */ CYG_ADDRWORD data /* data to write */ ) |
Description: | Set per thread data. Be careful with this, giving a bad index will cause an ASSERT if you have it turned on, but no other error checking is performed otherwise. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | nothing |
See Also: | cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr |
cyg_thread_add_destructor | |
Name: | cyg_thread_add_destructor ( ) - add a destructor |
---|---|
Synopsis: | cyg_bool_t cyg_thread_add_destructor ( cyg_thread_destructor_fn fn, /* destructor function */ cyg_addrword_t data /* argument to destructor */ ) |
Description: | This causes a destructor to be added to the calling thread. Destructors are called before the thread exits or is killed. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | "true" if the thread was added successfully, "false" otherwise. |
See Also: | cyg_thread_exit, cyg_thread_delete, cyg_thread_kill, cyg_thread_rem_destructor |
cyg_thread_rem_destructor | |
Name: | cyg_thread_rem_destructor ( ) - remove (disable) a destructor |
---|---|
Synopsis: | cyg_bool_t cyg_thread_rem_destructor ( cyg_thread_destructor_fn fn, /* destructor function */ cyg_addrword_t data /* argument to destructor */ ) |
Description: | This causes a destructor to be removed from the calling thread. Destructors are called before the thread exits or is killed. In order to successfully remove a destructor, both the "fn" and "data" argument must match exactly a previously installed destructor. |
Include: | #include <cyg/kernel/kapi.h> |
Returns: | "true" if a destructor was removed successfully, "false" otherwise. |
See Also: | cyg_thread_exit, cyg_thread_delete, cyg_thread_kill, cyg_thread_add_destructor, cyg_thread_rem_destructor |