Snapdragon® Telematics Application Framework (TelAF) Interface Specification
|
#include "le_cdata.h"
Go to the source code of this file.
Macros | |
#define | LE_THREAD_PRIORITY_RT_LOWEST LE_THREAD_PRIORITY_RT_1 |
Lowest real-time priority. More... | |
#define | LE_THREAD_PRIORITY_RT_HIGHEST LE_THREAD_PRIORITY_RT_32 |
Highest real-time priority. More... | |
#define | LE_THREAD_DEFINE_STATIC_STACK(name, bytes) |
#define | LE_THREAD_SET_STATIC_STACK(thread, name) le_thread_SetStack((thread), &_thread_stack_##name, sizeof(_thread_stack_##name)) |
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 |
#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_DEFINE_STATIC_STACK | ( | name, | |
bytes | |||
) |
Define a static thread stack region.
name | Stack variable name. |
bytes | Number of bytes in the stack. |
#define LE_THREAD_SET_STATIC_STACK | ( | thread, | |
name | |||
) | le_thread_SetStack((thread), &_thread_stack_##name, sizeof(_thread_stack_##name)) |
Set a static stack for a thread.
thread | Thread to set the stack for. |
name | Stack variable name that was previously passed to LE_THREAD_DEFINE_STATIC_STACK(). |
typedef struct le_thread* le_thread_Ref_t |
Reference to a thread of execution.
typedef void*(* le_thread_MainFunc_t) (void *context) |
Main functions for threads must look like this:
context | [IN] Context value that was passed to le_thread_Create(). |
typedef void(* le_thread_Destructor_t) (void *context) |
Destructor functions for threads must look like this:
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.
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.
LE_DECLARE_INLINE 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.
[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. |
le_result_t le_thread_SetPriority | ( | le_thread_Ref_t | thread, |
le_thread_Priority_t | priority | ||
) |
Sets the priority of a thread.
[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.
[in] | thread | |
[in] | size | Stack size, in bytes. May be rounded up to the nearest virtual memory page size. |
le_result_t le_thread_SetStack | ( | le_thread_Ref_t | thread, |
void * | stack, | ||
size_t | size | ||
) |
Sets the stack of a thread.
Setting the stack explicitly allows the caller to control the memory allocation of the thread's stack and, in some cases, control data. This can be useful for allocating the space out of static memory, for example.
The macro LE_THREAD_DEFINE_STATIC_STACK() may be used to create a statically allocated stack for use with this function, and LE_THREAD_SET_STATIC_STACK() may be used to call it properly.
[in] | thread | Thread instance. |
[in] | stack | Address of the lowest byte of the stack. This must be appropriately aligned (LE_THREAD_DEFINE_STATIC_STACK() will do this). |
[in] | size | Stack size, in bytes. |
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.
[in] | thread |
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.
[in] | thread |
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.
[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_Exit | ( | void * | resultValue | ) |
Terminates the calling thread.
[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_FULL_API 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.
[in] | threadToCancel | Thread to cancel. |
int le_thread_Sleep | ( | unsigned int | seconds | ) |
Causes the calling thread to sleep.
[in] | seconds | Time to sleep in seconds. |
le_thread_Ref_t le_thread_GetCurrent | ( | void | ) |
Gets the calling thread's thread reference.
void le_thread_GetName | ( | le_thread_Ref_t | threadRef, |
char * | buffPtr, | ||
size_t | buffSize | ||
) |
Gets the name of a given thread.
[in] | threadRef | Thread to get the name for. |
[out] | buffPtr | Buffer to store the name of the thread. |
[in] | buffSize | Size of the buffer. |
const char* le_thread_GetMyName | ( | void | ) |
Gets the name of the calling thread.
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.
See Thread Destructors for more information on destructors.
[in] | destructor | Function to be called. |
[in] | context | Parameter to pass to the destructor. |
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.
[in] | thread | Thread to attach the destructor to. |
[in] | destructor | Function to be called. |
[in] | context | Parameter to pass to the destructor. |
void le_thread_RemoveDestructor | ( | le_thread_DestructorRef_t | destructor | ) |
Removes a destructor function from the calling thread's list of destructors.
[in] | destructor | Reference to the destructor to remove. |
const _le_cdata_ThreadRec_t* _le_thread_GetCDataInstancePtr | ( | void | ) |
Gets the calling thread's component instance data record.
void _le_thread_SetCDataInstancePtr | ( | const _le_cdata_ThreadRec_t * | cdataPtr | ) |
Sets the calling thread's component instance data record.
cdataPtr | CData instance for the thread. |
LE_DECLARE_INLINE 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.
[in] | name | A name for the thread (will be copied, so can be temporary). |
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).
bool le_thread_IsLegatoThread | ( | void | ) |
Checks whether the calling thread is initialized as a Legato thread or not.