le_thread.h File Reference
Go to the source code of this file.
Macros | |
| #define | LE_THREAD_PRIORITY_RT_LOWEST LE_THREAD_PRIORITY_RT_1 |
| Lowest real-time priority. | |
| #define | LE_THREAD_PRIORITY_RT_HIGHEST LE_THREAD_PRIORITY_RT_32 |
| Highest real-time priority. | |
| #define | LE_THREAD_PRIORITY_NORMAL LE_THREAD_PRIORITY_MEDIUM |
Typedefs | |
| typedef struct le_thread * | le_thread_Ref_t |
| typedef void *(* | le_thread_MainFunc_t) (void *context) |
| typedef void(* | le_thread_Destructor_t) (void *context) |
| typedef struct le_thread_Destructor * | le_thread_DestructorRef_t |
Detailed Description
Legato Thread Control API include file.
Copyright (C) Sierra Wireless Inc.
Macro Definition Documentation
| #define LE_THREAD_PRIORITY_NORMAL LE_THREAD_PRIORITY_MEDIUM |
LE_THREAD_PRIORITY_NORMAL is deprecated, use LE_THREAD_PRIORITY_MEDIUM instead.
Typedef Documentation
| typedef void(* le_thread_Destructor_t) (void *context) |
Destructor functions for threads must look like this:
- Parameters
-
context [IN] Context parameter that was passed into le_thread_SetDestructor() when this destructor was registered.
| typedef struct le_thread_Destructor* le_thread_DestructorRef_t |
Reference to a registered destructor function.
| typedef void*(* le_thread_MainFunc_t) (void *context) |
Main functions for threads must look like this:
- Parameters
-
context [IN] Context value that was passed to le_thread_Create().
- Returns
- Thread result value. If the thread is joinable, then this value can be obtained by another thread through a call to vt_thread_Join(). Otherwise, the return value is ignored.
| typedef struct le_thread* le_thread_Ref_t |
Reference to a thread of execution.
- Note
- NULL can be used as an invalid value.
Enumeration Type Documentation
| enum le_thread_Priority_t |
Thread priority levels.
Real-time priority levels should be avoided unless absolutely necessary for the application. They are privileged levels and will therefore not be allowed unless the application is executed by an identity with the appropriate permissions. If a thread running at a real-time priority level does not block, no other thread at a lower priority level will run, so be careful with these.
- Note
- Higher numbers are higher priority.
Function Documentation
| void le_thread_AddChildDestructor | ( | le_thread_Ref_t | thread, |
| le_thread_Destructor_t | destructor, | ||
| void * | context | ||
| ) |
Registers a destructor function for a child thread. The destructor will be called by the child thread just before it terminates.
This can only be done before the child thread is started. After that, only the child thread can add its own destructors.
The reason for allowing another thread to register a destructor function is to avoid a race condition that can cause resource leakage when a parent thread passes dynamically allocated resources to threads that they create. This is only a problem if the child thread is expected to release the resources when they are finished with them, and the child thread may get cancelled at any time.
For example, a thread T1 could allocate an object from a memory pool, create a thread T2, and pass that object to T2 for processing and release. T2 could register a destructor function to release the resource whenever it terminates, whether through cancellation or normal exit. But, if it's possible that T2 could get cancelled before it even has a chance to register a destructor function for itself, the memory pool object could never get released. So, we allow T1 to register a destructor function for T2 before starting T2.
See Thread Destructors for more information on destructors.
- Parameters
-
[in] thread Thread to attach the destructor to. [in] destructor Function to be called. [in] context Parameter to pass to the destructor.
| le_thread_DestructorRef_t le_thread_AddDestructor | ( | le_thread_Destructor_t | destructor, |
| void * | context | ||
| ) |
Registers a destructor function for the calling thread. The destructor will be called by that thread just before it terminates.
A thread can register (or remove) its own destructor functions any time.
- Returns
- Reference to the destructor that can be passed to le_thread_RemoveDestructor().
See Thread Destructors for more information on destructors.
- Parameters
-
[in] destructor Function to be called. [in] context Parameter to pass to the destructor.
| le_result_t le_thread_Cancel | ( | le_thread_Ref_t | threadToCancel | ) |
Tells another thread to terminate. Returns immediately, but the termination of the thread happens asynchronously and is not guaranteed to occur when this function returns.
- Returns
- LE_OK if successful.
- LE_NOT_FOUND if the thread doesn't exist.
- Parameters
-
[in] threadToCancel Thread to cancel.
| void le_thread_CleanupLegatoThreadData | ( | void | ) |
Clean-up the thread-specific data that was initialized using le_thread_InitLegatoThreadData().
To prevent memory leaks, this must be called by the thread when it dies (unless the whole process is dying).
- Note
- This is not needed if the thread was started using le_thread_Start().
| le_thread_Ref_t le_thread_Create | ( | const char * | name, |
| le_thread_MainFunc_t | mainFunc, | ||
| void * | context | ||
| ) |
Creates a new Legato thread of execution. After creating the thread, you have the opportunity to set attributes before it starts. It won't start until le_thread_Start() is called.
- Returns
- A reference to the thread (doesn't return if fails).
- Parameters
-
[in] name Thread name (will be copied, so can be temporary). [in] mainFunc Thread's main function. [in] context Value to pass to mainFunc when it is called.
| void le_thread_Exit | ( | void * | resultValue | ) |
Terminates the calling thread.
- Parameters
-
[in] resultValue Result value. If this thread is joinable, this result can be obtained by another thread calling le_thread_Join() on this thread.
| le_thread_Ref_t le_thread_GetCurrent | ( | void | ) |
Gets the calling thread's thread reference.
- Returns
- Calling thread's thread reference.
| const char* le_thread_GetMyName | ( | void | ) |
Gets the name of the calling thread.
| void le_thread_GetName | ( | le_thread_Ref_t | threadRef, |
| char * | buffPtr, | ||
| size_t | buffSize | ||
| ) |
Gets the name of a given thread.
- Parameters
-
[in] threadRef Thread to get the name for. [out] buffPtr Buffer to store the name of the thread. [in] buffSize Size of the buffer.
| void le_thread_InitLegatoThreadData | ( | const char * | name | ) |
Initialize the thread-specific data needed by the Legato framework for the calling thread.
This is used to turn a non-Legato thread (a thread that was created using a non-Legato API, such as pthread_create() ) into a Legato thread.
- Note
- This is not needed if the thread was started using le_thread_Start().
- Parameters
-
[in] name A name for the thread (will be copied, so can be temporary).
| le_result_t le_thread_Join | ( | le_thread_Ref_t | thread, |
| void ** | resultValuePtr | ||
| ) |
"Joins" the calling thread with another thread. Blocks the calling thread until the other thread finishes.
After a thread has been joined with, its thread reference is no longer valid and must never be used again.
The other thread's result value (the value it returned from its main function or passed into le_thread_Exit()) can be obtained.
- Returns
- LE_OK if successful.
- LE_DEADLOCK if a thread tries to join with itself or two threads try to join each other.
- LE_NOT_FOUND if the other thread doesn't exist.
- LE_NOT_POSSIBLE if the other thread can't be joined with.
- Deprecated:
- the result code LE_NOT_POSSIBLE is scheduled to be removed before 15.04
- Warning
- The other thread must be "joinable". See le_thread_SetJoinable();
- It's an error for two or more threads try to join with the same thread.
- Parameters
-
[in] thread [out] resultValuePtr Ptr to where the finished thread's result value will be stored. Can be NULL if the result is not needed.
| void le_thread_RemoveDestructor | ( | le_thread_DestructorRef_t | destructor | ) |
Removes a destructor function from the calling thread's list of destructors.
- Parameters
-
[in] destructor Reference to the destructor to remove.
| void le_thread_SetJoinable | ( | le_thread_Ref_t | thread | ) |
Makes a thread "joinable", meaning that when it finishes, it will remain in existence until another thread "joins" with it by calling le_thread_Join(). By default, threads are not joinable and will be destroyed automatically when they finish.
- Parameters
-
[in] thread
| le_result_t le_thread_SetPriority | ( | le_thread_Ref_t | thread, |
| le_thread_Priority_t | priority | ||
| ) |
Sets the priority of a thread.
- Returns
- LE_OK if successful.
- LE_OUT_OF_RANGE if the priority level requested is out of range.
- Parameters
-
[in] thread [in] priority
| le_result_t le_thread_SetStackSize | ( | le_thread_Ref_t | thread, |
| size_t | size | ||
| ) |
Sets the stack size of a thread.
- Note
- It's generally not necessary to set the stack size. Some reasons why you might are:
- to increase it beyond the system's default stack size to prevent overflow for a thread that makes extremely heavy use of the stack;
- to decrease it to save memory when:
- running in a system that does not support virtual memory
- the thread has very tight real-time constraints that require that the stack memory be locked into physical memory to avoid page faults.
- Returns
- LE_OK if successful.
- LE_OVERFLOW if the stack size requested is too small.
- LE_OUT_OF_RANGE if the stack size requested is too large.
- Parameters
-
[in] thread [in] size Stack size, in bytes. May be rounded up to the nearest virtual memory page size.
| void le_thread_Start | ( | le_thread_Ref_t | thread | ) |
Starts a new Legato execution thread. After creating the thread, you have the opportunity to set attributes before it starts. It won't start until le_thread_Start() is called.
- Parameters
-
[in] thread