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;
etcpal_signal_t signal;
 
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_signal_create(&signal);
  
  EtcPalThreadParams thread_params = ETCPAL_THREAD_PARAMS_INIT;
  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);
  etcpal_signal_destroy(&signal);
  return 0;
}
 
void interrupt_handler(void)
{
  // Add some event to the queue
  event_queue[event_queue_current_size++] = new_event;
  etcpal_signal_post_from_isr(&signal);
}

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]

id

Signal 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]

id

Identifier 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]

id

Identifier 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]

id

Identifier 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]	id	Identifier for the signal for which to wait.
[in]	timeout_ms	Maximum 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]

id

Identifier 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]

id

Identifier for the signal for which to wait.

Returns

true: The signal was received.

false: The signal is invalid or an error occurred.