EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
signal (Signals)

Overview

Signal objects.

#include "etcpal/signal.h"

Sometimes also referred to as a binary semaphore or event. Used for thread synchronization; a call to etcpal_signal_wait() blocks until etcpal_signal_post() is called.

Signals are used to synchronize different threads around some event. For example:

Event event_queue[EVENT_QUEUE_SIZE];
size_t event_queue_current_size;
void event_thread(void* arg)
{
while (keep_running)
{
// Wait until we have queue items to process
// Note this is a simplified example; in real code you would probably want a mutex or
// critical section here as well.
if (etcpal_signal_wait(&signal))
{
// Handle all events currently in the queue
for (size_t i = 0; i < event_queue_current_size; ++i)
{
Event* event = &event_queue[i];
// Handle event somehow
}
event_queue_current_size = 0;
}
}
}
int main(void)
{
etcpal_thread_t event_thread_handle;
etcpal_thread_create(&event_thread_handle, &thread_params, event_thread, NULL);
// At shutdown time...
keep_running = false;
etcpal_thread_join(&event_thread_handle);
return 0;
}
void interrupt_handler(void)
{
// Add some event to the queue
event_queue[event_queue_current_size++] = new_event;
}
bool etcpal_signal_wait(etcpal_signal_t *id)
Wait for a signal.
bool etcpal_signal_create(etcpal_signal_t *id)
Create a new signal.
void etcpal_signal_destroy(etcpal_signal_t *id)
Destroy a signal object.
PLATFORM_DEFINED etcpal_signal_t
The signal identifier.
Definition: signal.dox:85
void etcpal_signal_post_from_isr(etcpal_signal_t *id)
Post a signal from an interrupt context.
etcpal_error_t etcpal_thread_create(etcpal_thread_t *id, const EtcPalThreadParams *params, void(*thread_fn)(void *), void *thread_arg)
Create a new thread.
PLATFORM_DEFINED etcpal_thread_t
The thread handle.
Definition: thread.dox:35
etcpal_error_t etcpal_thread_join(etcpal_thread_t *id)
Wait for a thread to finish execution.
#define ETCPAL_THREAD_PARAMS_INIT
A default initializer value for an EtcPalThreadParams structure.
Definition: thread.h:188
A set of parameters for an etcpal_thread.
Definition: thread.h:127

etcpal_signal implementations use different constructs under the hood on various platforms. Also, different platforms affect the behavior of certain functions.

Platform ETCPAL_SIGNAL_HAS_TIMED_WAIT ETCPAL_SIGNAL_HAS_POST_FROM_ISR Underlying Type
FreeRTOS Yes Yes Binary Semaphores
Linux No No pthread_cond
macOS No No pthread_cond
MQX Yes No Lightweight Events
Windows Yes No Event objects

Macros

#define ETCPAL_SIGNAL_HAS_TIMED_WAIT   /* platform-defined */
 Whether etcpal_signal_timed_wait() is meaningful on this platform. More...
 
#define ETCPAL_SIGNAL_HAS_POST_FROM_ISR   /* platform-defined */
 Whether etcpal_signal_post_from_isr() is meaningful on this platform. More...
 

Typedefs

typedef PLATFORM_DEFINED etcpal_signal_t
 The signal identifier. More...
 

Functions

bool etcpal_signal_create (etcpal_signal_t *id)
 Create a new signal. More...
 
bool etcpal_signal_wait (etcpal_signal_t *id)
 Wait for a signal. More...
 
bool etcpal_signal_try_wait (etcpal_signal_t *id)
 Try to wait for a signal. More...
 
bool etcpal_signal_timed_wait (etcpal_signal_t *id, int timeout_ms)
 Wait for a signal, giving up after a timeout. More...
 
void etcpal_signal_post (etcpal_signal_t *id)
 Post a signal. More...
 
void etcpal_signal_post_from_isr (etcpal_signal_t *id)
 Post a signal from an interrupt context. More...
 
void etcpal_signal_destroy (etcpal_signal_t *id)
 Destroy a signal object. More...
 

Macro Definition Documentation

◆ ETCPAL_SIGNAL_HAS_POST_FROM_ISR

#define ETCPAL_SIGNAL_HAS_POST_FROM_ISR   /* platform-defined */

Whether etcpal_signal_post_from_isr() is meaningful on this platform.

Some platforms have a different method for posting a signal from an interrupt context. If defined to 0, etcpal_signal_post_from_isr() executes the equivalent of etcpal_signal_post().

◆ ETCPAL_SIGNAL_HAS_TIMED_WAIT

#define ETCPAL_SIGNAL_HAS_TIMED_WAIT   /* platform-defined */

Whether etcpal_signal_timed_wait() is meaningful on this platform.

If defined to 0, etcpal_signal_timed_wait() executes the equivalent of etcpal_signal_try_wait() if given a timeout of 0, or etcpal_signal_wait() otherwise.

Typedef Documentation

◆ etcpal_signal_t

typedef PLATFORM_DEFINED etcpal_signal_t

The signal identifier.

Depending on the platform, this could be a scalar type or a struct.

Function Documentation

◆ etcpal_signal_create()

bool etcpal_signal_create ( etcpal_signal_t id)

Create a new signal.

Signals are created in the "unsignaled" state; that is, the first call to etcpal_signal_wait() will block.

Parameters
[out]idSignal identifier on which to create a signal. If this function returns true, id becomes valid for calls to other etcpal_signal API functions.
Returns
true: The signal was created.
false: The signal was not created.

◆ etcpal_signal_destroy()

void etcpal_signal_destroy ( etcpal_signal_t id)

Destroy a signal object.

Parameters
[in]idIdentifier for the signal to destroy.

◆ etcpal_signal_post()

void etcpal_signal_post ( etcpal_signal_t id)

Post a signal.

If no threads are waiting for the signal, puts the signal object in the "signaled" state (a subsequent call to etcpal_signal_wait() will return immediately). Otherwise, wakes up the first thread that waited for the signal.

Parameters
[in]idIdentifier for the signal to post.

◆ etcpal_signal_post_from_isr()

void etcpal_signal_post_from_isr ( etcpal_signal_t id)

Post a signal from an interrupt context.

This function is only meaningful on some platforms; namely, those which have a different method for posting a signal from an interrupt context. The value of ETCPAL_SIGNAL_HAS_POST_FROM_ISR can be used to determine whether this function is meaningful on the current platform. If it is defined to 0, this function simply executes the equivalent of etcpal_signal_post().

Parameters
[in]idIdentifier for the signal to post.

◆ etcpal_signal_timed_wait()

bool etcpal_signal_timed_wait ( etcpal_signal_t id,
int  timeout_ms 
)

Wait for a signal, giving up after a timeout.

This function is not honored on all platforms. The value of ETCPAL_SIGNAL_HAS_TIMED_WAIT can be used to determine whether this function is honored on the current platform. If it is defined to 0, this function executes the equivalent of etcpal_signal_try_wait() if timeout_ms is 0, or etcpal_signal_wait() otherwise.

Parameters
[in]idIdentifier for the signal for which to wait.
[in]timeout_msMaximum amount of time to wait for the signal, in milliseconds. If ETCPAL_WAIT_FOREVER is given, the result is the same as if etcpal_signal_wait() was called.
Returns
true: The signal was received.
false: The timeout expired, the signal was invalid or an error occurred.

◆ etcpal_signal_try_wait()

bool etcpal_signal_try_wait ( etcpal_signal_t id)

Try to wait for a signal.

If the signal is in the signaled state (etcpal_signal_post() has previously been called), puts the signal in the non-signaled state and returns true. Otherwise, returns false.

Parameters
[in]idIdentifier for the signal to poll.
Returns
true: The signal was received.
false: The signal is not in a signaled state (or the signal is invalid).

◆ etcpal_signal_wait()

bool etcpal_signal_wait ( etcpal_signal_t id)

Wait for a signal.

If the signal is in the signaled state (etcpal_signal_post() has previously been called), puts the signal in the non-signaled state and returns true. Otherwise, blocks until a call to etcpal_signal_post() is made on the signal object and returns true.

Parameters
[in]idIdentifier for the signal for which to wait.
Returns
true: The signal was received.
false: The signal is invalid or an error occurred.