Struct SemaphoreRef

pub struct SemaphoreRef<'l>(/* private fields */);

Like a sem_t * as a borrow of a semaphore that is known to be initialized and so valid to do operations on.

Implementations

impl<'l> SemaphoreRef<'l>

pub fn post(&self) -> Result<(), ()>

Like sem_post, and async-signal-safe like that.

It is safe for this to be called from a signal handler. That is a primary use-case for POSIX Semaphores versus other better synchronization APIs (which shouldn’t be used in signal handlers).

This synchronizes memory with respect to other threads on all successful calls. That is a primary use-case so that memory writes to other objects, sequenced before a call to this, will be visible to other threads after returning from Self::wait() (et al). If this returns an error, it is unspecified whether the invocation causes memory to be synchronized. (See: POSIX’s requirements.)

Errors

If sem_post() does. errno is set to indicate the error. Its EINVAL case should be impossible.

pub fn wait(&self) -> Result<(), ()>

Like sem_wait.

Might block the calling thread.

This synchronizes memory with respect to other threads on all successful calls. That is a primary use-case so that other threads’ memory writes to other objects, sequenced before Self::post(), will be visible to the current thread after returning from this. If this returns an error, it is unspecified whether the invocation causes memory to be synchronized. (See: POSIX’s requirements.)

Errors

If sem_wait() does. errno is set to indicate the error. Its EINVAL case should be impossible.

pub fn try_wait(&self) -> Result<(), ()>

Like sem_trywait.

Won’t block the calling thread.

This synchronizes memory with respect to other threads on all successful calls. That is a primary use-case so that other threads’ memory writes to other objects, sequenced before Self::post(), will be visible to the current thread after returning from this. If this returns an error, it is unspecified whether the invocation causes memory to be synchronized. (See: POSIX’s requirements.)

Errors

If sem_trywait() does. errno is set to indicate the error. Its EINVAL case should be impossible.

pub fn get_value(&self) -> c_int

Like sem_getvalue.

Trait Implementations

impl<'l> Clone for SemaphoreRef<'l>

fn clone(&self) -> SemaphoreRef<'l>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SemaphoreRef<'_>

Shows the sem_t * pointer.

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

Formats the value using the given formatter.

impl Display for SemaphoreRef<'_>

Human-readable representation that shows the semaphore’s current count value.

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

Formats the value using the given formatter.

impl PartialEq for SemaphoreRef<'_>

Compare by sem_t * pointer equality.

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'l> Copy for SemaphoreRef<'l>

impl Eq for SemaphoreRef<'_>

impl Send for SemaphoreRef<'_>

SAFETY: Ditto.

impl Sync for SemaphoreRef<'_>

SAFETY: The POSIX Semaphores API intends for sem_t *, after the pointed-to instance is initialized, to be shared between threads and its operations are thread-safe (similar to atomic types). Our API ensures by construction that multiple threads can only operate on a sem_t * after initialization. Therefore we can expose this in Rust as having “thread-safe interior mutability”.