Struct Semaphore 

pub struct Semaphore(/* private fields */);

Semaphore types for signaling and resource management. POSIX backend for SemaphoreFn. Built directly on a pthread_mutex_t + pthread_cond_t pair rather than sem_t, so signal() can be bounded by a user-supplied max_count and the mutex can use priority inheritance — neither of which plain POSIX unnamed semaphores support.

Fields (unnamed, accessed as self.0/self.1/self.2): the pthread handle, the current count, and the fixed maximum count.

Implementations

impl Semaphore

pub fn new(max_count: UBaseType, initial_count: UBaseType) -> Result<Self>

Creates a new semaphore with the given maximum and initial count. Semaphore::signal never raises the count above max_count; a binary semaphore is just max_count == 1.

Examples

use osal_rs::os::*;

// Binary semaphore, starts "empty".
let sem = Semaphore::new(1, 0).unwrap();
assert_eq!(sem.wait_from_isr(), osal_rs::utils::OsalRsBool::False);

Methods from Deref<Target = SemaphoreHandle>

pub fn is_empty(&self) -> bool

Returns true if this handle is still in its never-initialized (or already-deleted) state, i.e. both the mutex and condition variable are all-zero.

Examples

use osal_rs::os::types::ClockMonotonicHandle;

assert!(ClockMonotonicHandle::default().is_empty());

Trait Implementations

impl Debug for Semaphore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Semaphore

type Target = ClockMonotonicHandle

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for Semaphore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Semaphore

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Semaphore for Semaphore

fn is_null(&self) -> bool

Returns true if this semaphore is never-initialized-or-already-deleted.

Unlike crate::os::EventGroupFn::is_null, the count is checked too, so a live semaphore that just happens to be momentarily empty (count == 0) is never mistaken for a deleted one.

Examples

use osal_rs::os::*;

let mut sem = Semaphore::new(1, 0).unwrap();
assert!(!sem.is_null());

sem.delete();
assert!(sem.is_null());

fn wait(&self, ticks_to_wait: impl ToTick) -> OsalRsBool

Blocks until a unit is available or ticks_to_wait elapses (accepts any ToTick value, e.g. a raw tick count or a core::time::Duration; pass TickType::MAX ticks to wait forever), decrementing the count on success.

Examples

use osal_rs::os::*;
use osal_rs::utils::OsalRsBool;
use core::time::Duration;

let sem = Semaphore::new(1, 1).unwrap();
assert_eq!(sem.wait(Duration::from_millis(100)), OsalRsBool::True);

// Count is now 0: waiting again times out instead of blocking forever.
assert_eq!(sem.wait(Duration::from_millis(10)), OsalRsBool::False);

fn wait_from_isr(&self) -> OsalRsBool

ISR-safe variant of Semaphore::wait. POSIX has no interrupt context of its own, so this never blocks (trylock instead of lock, and no timeout parameter); it returns OsalRsBool::False both when the mutex is contended and when the count is simply zero.

Examples

use osal_rs::os::*;
use osal_rs::utils::OsalRsBool;

let sem = Semaphore::new(1, 1).unwrap();
assert_eq!(sem.wait_from_isr(), OsalRsBool::True);
assert_eq!(sem.wait_from_isr(), OsalRsBool::False);

fn signal(&self) -> OsalRsBool

Increments the count (unless already at max_count) and wakes any thread blocked in Semaphore::wait. Returns OsalRsBool::False if the semaphore was already at max_count.

Examples

use osal_rs::os::*;
use osal_rs::utils::OsalRsBool;

let sem = Semaphore::new(1, 0).unwrap();
assert_eq!(sem.signal(), OsalRsBool::True);

// Already at max_count: signalling again fails.
assert_eq!(sem.signal(), OsalRsBool::False);

fn signal_from_isr(&self) -> OsalRsBool

ISR-safe variant of Semaphore::signal. Fails with OsalRsBool::False instead of blocking if the mutex is contended.

Examples

use osal_rs::os::*;
use osal_rs::utils::OsalRsBool;

let sem = Semaphore::new(1, 0).unwrap();
assert_eq!(sem.signal_from_isr(), OsalRsBool::True);

fn delete(&mut self)

Destroys the underlying pthread objects and resets this semaphore to its “null” state. Safe to call more than once, and called automatically on Drop if not called explicitly.

Examples

use osal_rs::os::*;

let mut sem = Semaphore::new(1, 0).unwrap();
sem.delete();
assert!(sem.is_null());

impl Send for Semaphore

impl Sync for Semaphore