Struct NamedSemaphore

pub struct NamedSemaphore { /* private fields */ }

Named semaphore.

See lib level documentation for how to use this struct.

Implementations

impl NamedSemaphore

pub fn create<T: AsRef<str>>(name: T, initial_value: u32) -> Result<Self, Error>

Create a named semaphore with name and initial value, or open it if there has already been a semaphore with the same name across system (in which case, the name and initial_value are ignored).

In Linux, name should starts with “/” and is no longer than 250, and does not contain “/” after the prefix “/”. initial_value should not greater than SEM_VALUE_MAX. The underlined implementation is sem_open.

In Windows, name should be no longer than MAX_PATH. initial_value should fit in i32 and not less than 0, the maximum count of the semaphore is set to the initial value. The underlying implementation is CreateSemaphore

Notes

The named semaphore will be closed when the NamedSemaphore drops.

In Windows, if all accesses to named semaphore have been closed, the semaphore will be destroyed.

In Linux, the named semaphore created will not be destroyed even if all processes accessing it has been terminated. The named semaphore can be destroyed by removing corresponding file in /dev/shm, or using sem_unlink, or restarting the operating system.

pub fn create_with_max<T: AsRef<str>>( name: T, initial_value: u32, max_value: u32, ) -> Result<Self, Error>

Create a named semaphore with name and initial value, or open it if there has already been a semaphore with the same name across system (in which case, the name and initial_value are ignored). Max value is used on windows, where the semaphore can have an internal limit. It does not affect linux.

In Linux, name should starts with “/” and is no longer than 250, and does not contain “/” after the prefix “/”. initial_value should not greater than SEM_VALUE_MAX. The underlined implementation is sem_open. Max value does not have an effect on linux.

In Windows, name should be no longer than MAX_PATH. initial_value and max_value should fit in i32 and not less than 0. The underlying implementation is CreateSemaphore

Notes

The named semaphore will be closed when the NamedSemaphore drops.

In Windows, if all accesses to named semaphore have been closed, the semaphore will be destroyed.

In Linux, the named semaphore created will not be destroyed even if all processes accessing it has been terminated. The named semaphore can be destroyed by removing corresponding file in /dev/shm, or using sem_unlink, or restarting the operating system.

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

Wait for the semaphore and decrease it, block if current semaphore’s count is 0.

In Linux, the underlined implementation is sem_wait.

In Windows, the underlined implementation is WaitForSingleObject.

pub fn timed_wait(&mut self, dur: Duration) -> Result<(), Error>

Wait for the semaphore and decrease it, block for dur if current semaphore’s count is 0.

In Linux, the underlined implementation is sem_timedwait.

In Windows, the underlined implementation is WaitForSingleObject.

Note that macOS did not provide such functionality, see https://stackoverflow.com/q/641126/10005095.

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

Wait for the semaphore and decrease it, raise Error::WouldBlock if current semaphore’s count is 0.

In Linux, the underlined implementation is sem_trywait.

In Windows, the underlined implementation is WaitForSingleObject.

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

Release the semaphore and increase it.

In Linux, the underlined implementation is sem_post.

In Windows, the underlined implementation is ReleaseSemaphore.

pub fn wait_then_post<T, F: FnOnce() -> T>( &mut self, action: F, ) -> Result<T, Error>

A convenient method to wait-then-post the semaphore.