v2.0.0
Functions
sem
High Level APIs » pico_sync

Semaphore API for restricting access to a resource. More...

## Functions
void | sem_init (semaphore_t *sem, int16_t initial_permits, int16_t max_permits)
| Initialise a semaphore structure. More...
int | sem_available (semaphore_t *sem)
| Return number of available permits on the semaphore. More...
bool | sem_release (semaphore_t *sem)
| Release a permit on a semaphore. More...
void | sem_reset (semaphore_t *sem, int16_t permits)
| Reset semaphore to a specific number of available permits. More...
void | sem_acquire_blocking (semaphore_t *sem)
| Acquire a permit from the semaphore. More...
bool | sem_acquire_timeout_ms (semaphore_t *sem, uint32_t timeout_ms)
| Acquire a permit from a semaphore, with timeout. More...
bool | sem_acquire_timeout_us (semaphore_t *sem, uint32_t timeout_us)
| Acquire a permit from a semaphore, with timeout. More...
bool | sem_acquire_block_until (semaphore_t *sem, absolute_time_t until)
| Wait to acquire a permit from a semaphore until a specific time. More...
bool | sem_try_acquire (semaphore_t *sem)
| Attempt to acquire a permit from a semaphore without blocking. More...

## Detailed Description

Semaphore API for restricting access to a resource.

A semaphore holds a number of available permits. `sem_acquire` methods will acquire a permit if available (reducing the available count by 1) or block if the number of available permits is 0. sem_release() increases the number of available permits by one potentially unblocking a `sem_acquire` method.

Note that sem_release() may be called an arbitrary number of times, however the number of available permits is capped to the max_permit value specified during semaphore initialization.

Although these semaphore related functions can be used from IRQ handlers, it is obviously preferable to only release semaphores from within an IRQ handler (i.e. avoid blocking)

## Function Documentation

## ◆ sem_acquire_block_until()

bool sem_acquire_block_until | ( | semaphore_t * | sem,
|  | absolute_time_t | until
| ) |  |

Wait to acquire a permit from a semaphore until a specific time.

This function will block and wait if no permits are available, until the specified timeout time. If the timeout is reached the function will return false, otherwise it will return true.

Parameters

  sem | Pointer to semaphore structure
  until | The time after which to return if the sem is not available.

Returns
  true if permit was acquired, false if the until time was reached before acquiring.

## ◆ sem_acquire_blocking()

void sem_acquire_blocking | ( | semaphore_t * | sem | ) |

Acquire a permit from the semaphore.

This function will block and wait if no permits are available.

Parameters

  sem | Pointer to semaphore structure

## ◆ sem_acquire_timeout_ms()

bool sem_acquire_timeout_ms | ( | semaphore_t * | sem,
|  | uint32_t | timeout_ms
| ) |  |

Acquire a permit from a semaphore, with timeout.

This function will block and wait if no permits are available, until the defined timeout has been reached. If the timeout is reached the function will return false, otherwise it will return true.

Parameters

  sem | Pointer to semaphore structure
  timeout_ms | Time to wait to acquire the semaphore, in milliseconds.

Returns
  false if timeout reached, true if permit was acquired.

## ◆ sem_acquire_timeout_us()

bool sem_acquire_timeout_us | ( | semaphore_t * | sem,
|  | uint32_t | timeout_us
| ) |  |

Acquire a permit from a semaphore, with timeout.

This function will block and wait if no permits are available, until the defined timeout has been reached. If the timeout is reached the function will return false, otherwise it will return true.

Parameters

  sem | Pointer to semaphore structure
  timeout_us | Time to wait to acquire the semaphore, in microseconds.

Returns
  false if timeout reached, true if permit was acquired.

## ◆ sem_available()

int sem_available | ( | semaphore_t * | sem | ) |

Return number of available permits on the semaphore.

Parameters

  sem | Pointer to semaphore structure

Returns
  The number of permits available on the semaphore.

## ◆ sem_init()

void sem_init | ( | semaphore_t * | sem,
|  | int16_t | initial_permits,
|  | int16_t | max_permits
| ) |  |

Initialise a semaphore structure.

Parameters

  sem | Pointer to semaphore structure
  initial_permits | How many permits are initially acquired
  max_permits | Total number of permits allowed for this semaphore

## ◆ sem_release()

bool sem_release | ( | semaphore_t * | sem | ) |

Release a permit on a semaphore.

Increases the number of permits by one (unless the number of permits is already at the maximum). A blocked `sem_acquire` will be released if the number of permits is increased.

Parameters

  sem | Pointer to semaphore structure

Returns
  true if the number of permits available was increased.

## ◆ sem_reset()

void sem_reset | ( | semaphore_t * | sem,
|  | int16_t | permits
| ) |  |

Reset semaphore to a specific number of available permits.

Reset value should be from 0 to the max_permits specified in the init function

Parameters

  sem | Pointer to semaphore structure
  permits | the new number of available permits

## ◆ sem_try_acquire()

bool sem_try_acquire | ( | semaphore_t * | sem | ) |

Attempt to acquire a permit from a semaphore without blocking.

This function will return false without blocking if no permits are available, otherwise it will acquire a permit and return true.

Parameters

  sem | Pointer to semaphore structure

Returns
  true if permit was acquired.