File semaphore.h

Semaphore communication primitive.

Supports both binary and counting semaphores.

Typedefs

typedef struct semaphore Semaphore

Enums

enum res_codes_semaphore

Values:

enumerator RES_SEMAPHORE_FULL

Functions

Semaphore *semaphore_create_binary(void)

Create a binary semaphore of a particular size.

Note

This is equivalent to creating a semaphore with slot_count set to 1.

Returns:

the created semaphore, or NULL.

Semaphore *semaphore_create_binary_static(Semaphore *semaphore)

Initialise a statically allocated binary semaphore.

Note

This is equivalent to creating a semaphore with slot_count set to 1.

Parameters:

semaphore – Semaphore to initialise.

Returns:

the same semaphore as the input.

Semaphore *semaphore_create(size_t slot_count)

Create a bounded semaphore of a particular size.

Parameters:

slot_count – Maximum number of allowed concurrent acquisitions.

Returns:

the created semaphore, or NULL.

Semaphore *semaphore_create_static(Semaphore *semaphore, size_t slot_count)

Initialise a statically allocated semaphore.

Parameters:

  • semaphore – Semaphore to initialise.

  • slot_count – Maximum number of allowed concurrent acquisitions.

Returns:

the same semaphore as the input.

void semaphore_free(Semaphore *semaphore)

Frees a semaphore created using the dynamic allocation functions.

Warning

Freeing a semaphore not created by semaphore_create* is causes undefined behaviour.

Parameters:

semaphore – Semaphore to free (binary or counting).

Result semaphore_acquire(Semaphore *semaphore, PlatformTick delay_ticks)

Acquire the semaphore, waiting forever.

Parameters:

  • semaphore – Semaphore to acquire.

  • delay_ticks – Number of ticks to wait before timing out.

Return values:

  • RES_OK – If semaphore was acquired

  • RES_TIMEOUT – The maximum timeout duration has been reached.

Result semaphore_acquire_no_wait(Semaphore *semaphore)

Acquire the semaphore, does not wait.

Parameters:

semaphore – Semaphore to acquire.

Return values:

  • RES_OK – If semaphore was acquired.

  • RES_SEMAPHORE_FULL – If the semaphore has no available slots to acquire.

Result semaphore_acquire_from_isr(Semaphore *semaphore)

Acquire the semaphore from an ISR, does not block.

Note

This should be called from an ISR context only.

Parameters:

semaphore – Semaphore to acquire.

Return values:

  • RES_OK – semaphore has been acquired

  • RES_TIMEOUT – if the semaphore cannot be acquired.

Result semaphore_release(Semaphore *semaphore)

Release the semaphore.

Parameters:

semaphore – Semaphore to release.

Return values:

  • RES_OK – Semaphore has been released.

  • RES_OVERFLOW – Semaphore has already hit the maximum number of releases. (A double release has occurred.)

Result semaphore_release_from_isr(Semaphore *semaphore)

Release the semaphore from an ISR, does not block.

Note

This should be called from an ISR context only.

Parameters:

semaphore – Semaphore to acquire.

Return values:

  • RES_OK – semaphore has been released.

  • RES_OVERFLOW – if the semaphore could not be released.

  • RES_NOTIFY_FAILED – if the scheduler notification has failed.

struct semaphore

Public Members

size_t volatile slots_remaining
size_t slot_count