Embedded Multicore Building Blocks V1.0.0
Typedefs | Enumerations | Functions

Threads supporting thread-to-core affinities. More...

Typedefs

typedef opaque_type embb_thread_t
 Opaque type representing a thread of execution. More...
 
typedef int(* embb_thread_start_t) (void *)
 Thread start function pointer type. More...
 

Enumerations

enum  embb_thread_priority_t {
  EMBB_THREAD_PRIORITY_IDLE, EMBB_THREAD_PRIORITY_LOWEST, EMBB_THREAD_PRIORITY_BELOW_NORMAL, EMBB_THREAD_PRIORITY_NORMAL,
  EMBB_THREAD_PRIORITY_ABOVE_NORMAL, EMBB_THREAD_PRIORITY_HIGHEST, EMBB_THREAD_PRIORITY_TIME_CRITICAL
}
 Thread priority type. More...
 

Functions

unsigned int embb_thread_get_max_count ()
 Returns the maximum number of threads handled by EMB2. More...
 
void embb_thread_set_max_count (unsigned int max)
 Sets maximum number of threads handled by EMBB. More...
 
embb_thread_t embb_thread_current ()
 Returns the calling thread (that is, this thread). More...
 
void embb_thread_yield ()
 Reschedule the current thread for later execution. More...
 
int embb_thread_create (embb_thread_t *thread, const embb_core_set_t *core_set, embb_thread_start_t function, void *arg)
 Creates and runs a thread. More...
 
int embb_thread_create_with_priority (embb_thread_t *thread, const embb_core_set_t *core_set, embb_thread_priority_t priority, embb_thread_start_t function, void *arg)
 Creates and runs a thread. More...
 
int embb_thread_join (embb_thread_t *thread, int *result_code)
 Waits until the given thread has finished execution. More...
 
int embb_thread_equal (const embb_thread_t *lhs, const embb_thread_t *rhs)
 Compares two threads represented by their handles for equality. More...
 

Detailed Description

Threads supporting thread-to-core affinities.

Provides an abstraction from platform-specific threading implementations to create, manage, and join threads of execution. Support for thread-to-core affinities is given on thread creation by using the core set functionality.

Typedef Documentation

typedef opaque_type embb_thread_t

Opaque type representing a thread of execution.

typedef int(* embb_thread_start_t) (void *)

Thread start function pointer type.

The return value can be used to return a user-defined exit code when the thread is joined.

Enumeration Type Documentation

Thread priority type.

Function Documentation

unsigned int embb_thread_get_max_count ( )

Returns the maximum number of threads handled by EMB2.

The maximum thread number concerns all threads in a program using EMB2 functionalities or data structures, regardless of whether a thread is started by EMB2 or other threading libraries. Each thread that makes use of EMB2 at least once consumes one entry in the internal tables. The entry is permanently consumed during a program run, even if the thread does not exist any longer. If more threads than the maximum thread count access EMB2, undefined behavior or abortion of program execution can occur.

Returns
Maximum number of threads
Concurrency
Thread-safe and lock-free
See also
embb_thread_set_max_count()
void embb_thread_set_max_count ( unsigned int  max)

Sets maximum number of threads handled by EMBB.

It needs to be set before any EMB2 functionalities are used or data structures are defined, unless the default value is sufficient.

Concurrency
Not thread-safe
See also
embb_thread_get_max_count()
Parameters
[in]maxMaximum number of threads
embb_thread_t embb_thread_current ( )

Returns the calling thread (that is, this thread).

The returned handle is only valid for the thread calling the function.

Returns
Calling thread
Concurrency
Thread-safe
void embb_thread_yield ( )

Reschedule the current thread for later execution.

This is only a request, the realization depends on the implementation and the scheduler employed by the operating system.

Concurrency
Thread-safe
int embb_thread_create ( embb_thread_t thread,
const embb_core_set_t core_set,
embb_thread_start_t  function,
void *  arg 
)

Creates and runs a thread.

Precondition
The given thread is not running and has not yet been successfully joined.
Postcondition
On success, the given thread has started to run.
Returns
EMBB_SUCCESS if the thread could be created.
EMBB_NOMEM if there was insufficient amount of memory
EMBB_ERROR otherwise.
Dynamic memory allocation
Dynamically allocates a small constant amount of memory to store the function and argument pointers. This memory is freed when the thread is joined.
Concurrency
Not thread-safe
See also
embb_thread_join()
Parameters
[out]threadThread to be run
[in]core_setSet of cores on which the thread shall be executed. Can be NULL to indicate automatic thread scheduling by the OS.
[in]functionFunction which is executed by the thread when started. Has to be of type embb_thread_start_t.
[in,out]argArgument to thread start function. Can be NULL.
int embb_thread_create_with_priority ( embb_thread_t thread,
const embb_core_set_t core_set,
embb_thread_priority_t  priority,
embb_thread_start_t  function,
void *  arg 
)

Creates and runs a thread.

Precondition
The given thread is not running and has not yet been successfully joined.
Postcondition
On success, the given thread has started to run.
Returns
EMBB_SUCCESS if the thread could be created.
EMBB_NOMEM if there was insufficient amount of memory
EMBB_ERROR otherwise.
Dynamic memory allocation
Dynamically allocates a small constant amount of memory to store the function and argument pointers. This memory is freed when the thread is joined.
Concurrency
Not thread-safe
See also
embb_thread_join()
Parameters
[out]threadThread to be run
[in]core_setSet of cores on which the thread shall be executed. Can be NULL to indicate automatic thread scheduling by the OS.
[in]priorityPriority to run the thread at.
[in]functionFunction which is executed by the thread when started. Has to be of type embb_thread_start_t.
[in,out]argArgument to thread start function. Can be NULL.
int embb_thread_join ( embb_thread_t thread,
int *  result_code 
)

Waits until the given thread has finished execution.

Precondition
The given thread has been successfully created using embb_thread_create().
Postcondition
If successful, the thread has finished execution and all memory associated to the thread has been freed.
Returns
EMBB_SUCCESS if thread was joined
EMBB_ERROR otherwise
Concurrency
Not thread-safe
See also
embb_thread_create()
Parameters
[in,out]threadThread to be joined
[out]result_codeMemory location (or NULL) for thread result code
int embb_thread_equal ( const embb_thread_t lhs,
const embb_thread_t rhs 
)

Compares two threads represented by their handles for equality.

Returns
Non-zero, if equal
0, otherwise
Concurrency
Not thread-safe
Parameters
[in]lhsFirst thread (left-hand side of equality sign)
[in]rhsSecond thread (right-hand side of equality sign)