le_thread.h File Reference

static uint8_t _thread_stack_##name[LE_THREAD_STACK_EXTRA_SIZE +                \
        ((bytes) < LE_THREAD_STACK_MIN_SIZE ? LE_THREAD_STACK_MIN_SIZE : (bytes))]  \
        __attribute__((aligned(LE_THREAD_STACK_ALIGNMENT)))
le_ref_Map::name
char name[LIMIT_MAX_SAFE_REF_NAME_BYTES]
Descriptive name for debugging. 
Definition: le_safeRef.h:234

Define a static thread stack region.

Parameters

name	Stack variable name.
bytes	Number of bytes in the stack.

Set a static stack for a thread.

See also

le_thread_SetStack() for details.

Parameters

thread	Thread to set the stack for.
name	Stack variable name that was previously passed to LE_THREAD_DEFINE_STATIC_STACK().

Returns

Return value of le_thread_SetStack().

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.

Reference to a registered destructor function.

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.

Reference to a thread of execution.

Note

NULL can be used as an invalid value.

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.

Gets the calling thread's component instance data record.

Sets the calling thread's component instance data record.

Parameters

cdataPtr

CData instance for the thread.

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.

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.

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.

Note

This function is not available on RTOS.

Returns

• LE_OK if successful.
• LE_NOT_FOUND if the thread doesn't exist.

Parameters

[in]

threadToCancel

Thread to cancel.

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().

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.

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.

Returns

A reference to the thread (doesn't return if fails).

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.

Gets the calling thread's thread reference.

Returns

Calling thread's thread reference.

Gets the name of the calling thread.

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.

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.

Parameters

[in]

name

A name for the thread (will be copied, so can be temporary).

Note

This is not needed if the thread was started using le_thread_Start().

"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_FAULT if the other thread can't be joined with.

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.

Removes a destructor function from the calling thread's list of destructors.

Parameters

[in]

destructor

Reference to the destructor to remove.

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

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

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.

Attention

In general, this function is only useful on embedded, RTOS based systems in order to perform up-front allocation of thread resources. On more capable systems it is safer to allow the operating system to set up the stack (which may optionally be sized using le_thread_SetStackSize()).

Returns

• LE_OK if successful.
• LE_BAD_PARAMETER if the size or stack is invalid (NULL or improperly aligned).

Parameters

[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.

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.

Causes the calling thread to sleep.

Returns

• 0 if the sleep is successful.
• -1 if the call is interrupted by a signal handler or encounters an error.

Note

This function is not a full equivalence of nanosleep() as the remaining sleep time will not be available to the caller if nanosleep() returns due to being interrupted by a signal.

Parameters

[in]

seconds

Time to sleep in seconds.

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