An os_sysv_semaphore is an object that manages one or more shared resources. Unlike most synchronization classes, System V semaphores can be used between processes. These semaphores are primarily used for synchronization of resources shared by multiple processes. When a semaphore is constructed, the number of available resources is specified and stored inside the semaphore as a counter.

When a process uses obtain() to obtain n resources from a semaphore, and the semaphore's counter is greater than or equal to n , the counter is decremented by n and the function returns immediately. However, if the counter is less than n , the process is suspended until the resources are available.

When a process uses release() to release n resources to a semaphore, the semaphore's counter is incremented by n and the function returns immediately.

A problem can occur if a process obtains a resource and then terminates abnormally before releasing it. To avoid this, you can specify the O_UNDO flag when using obtain() or release() , which classifies the operation as "undoable." When a process terminates, all "undoable" operations are automatically reversed. For example, if a resource was obtained, it is released. Similarly, if a resource was released, it is obtained. You can specify that an operation is non-blocking by using the O_NONBLOCK option. If an operation is performed that would block, it generates an EAGAIN error and immediately returns.

An os_sysv_semaphore contains a pointer to an os_sysv_semaphore_array . You can access its underlying array and obtain additional status information directly from the semaphores. You can copy and assign an os_sysv_semaphore object, and the object reference counts the underlying os_sysv_semaphore_array , permitting efficient pass by value.

Legal open control:	`O_OPEN, O_CREAT, O_EXCL`
Legal I/O control:	`O_NONBLOCK, O_UNDO`
Default I/O control:	0 (blocking, no undo)

Interface

Constructor

os_sysv_semaphore( os_vid_t id )

Constructs an object to reference the existing semaphore with id .

Throws: os_unix_toolkit_error

Constructor

os_sysv_semaphore( const os_key& key )

Constructs an object to reference the existing semaphore with key .

Throws: os_unix_toolkit_error

Constructor

os_sysv_semaphore( int initial_value , os_mode_t mode )

Constructs an object to reference a new semaphore with a private key, initial_value , and accesses permissions mode .

Throws: os_unix_toolkit_error

Constructor

os_sysv_semaphore( const os_key& key , os_open_t open , int initial_value , os_mode_t mode )

Constructs an object to reference a new semaphore with key , initial_value , open control flags open , and access permissions mode . If a semaphore with key already exists, references the existing semaphore and ignores the mode and initial_value parameters.

Throws: os_unix_toolkit_error

Constructor

os_sysv_semaphore( const os_sysv_semaphore& semaphore )

Constructs an object to reference the same semaphore as semaphore .

Destructor

~os_sysv_semaphore()

Destroys an object. The object disconnects from the semaphore array, which self-destructs if it is allocated on the heap and the object is the last semaphore to reference it.

bool operator<( const os_sysv_semaphore& semaphore ) const

Returns true if the object is considered less than semaphore .

const os_sysv_semaphore& operator=( const os_sysv_semaphore& semaphore )

References the same semaphore as semaphore .

bool operator==( const os_sysv_semaphore& semaphore ) const

Returns true if the object is the same semaphore as semaphore .

(os_vid_t)

operator os_vid_t() const

Returns the IPC ID.

array

const os_sysv_semaphore_array& array() const

Returns a reference to the semaphore array.

clear

void clear()

Flushes any pending operations without executing them.

count_waiting_for_increase

int count_waiting_for_increase() const

Returns the number of processes that are waiting for the value to increase.

Throws: os_unix_toolkit_error

count_waiting_for_zero

int count_waiting_for_zero() const

Returns the number of processes that are waiting for the value to be zero.

Throws: os_unix_toolkit_error

defined

bool defined() const

Returns true if the object references a valid semaphore array.

Throws: os_unix_toolkit_error

down

void down( os_ioctl_t control )

Same as

obtain(
    1,

control ) . The default value of control is zero.

execute

void execute()

Executes all operations pending for the associated semaphore array.

Throws: os_unix_toolkit_error

index

int index() const

Returns the index in the semaphore array.

last_operator

os_pid_t last_operator() const

Returns the process ID of the last process that operated on this object.

Throws: os_unix_toolkit_error

lock

void lock( os_ioctl_t control )

Same as

obtain(
    1,

control ) .

obtain

void obtain( int control , os_ioctl_t control )

Decrements the value by amount , using the I/O control control (default 0). This function can be recorded.

Throws: os_unix_toolkit_error

obtain

void obtain()

Decrements the value by one. This function can be recorded.

Throws: os_unix_toolkit_error

print

void print( ostream& stream ) const

Prints ID and index to stream .

void P( os_ioctl_t control )

Same as

obtain(
    1,

control ) .

record

void record( bool flag )

Sets the record mode of the associated semaphore array to flag (default true ).

record

bool record() const

Returns true if the associated semaphore array is in record mode.

release

void release( int amount , os_ioctl_t control )

Increments the value by amount , using the I/O control control (default 0). This function can be recorded.

Throws: os_unix_toolkit_error

release

void release()

Increments the value by 1. This function can be recorded.

Throws: os_unix_toolkit_error

remove

void remove()

Removes the associated semaphore array from the operating system. Any process that attempts to access its semaphores after this operation generates an error.

Throws: os_unix_toolkit_error

signal

void signal( os_ioctl_t control )

Same as

release(
    1,

control ) .

unlock

void unlock( os_ioctl_t control )

Same as

release(
    1,

control ) .

void up( os_ioctl_t control )

Same as

release(
    1,

control ) .

value

int value() const

Returns the current value.

Throws: os_unix_toolkit_error

value

void value( int new_value )

Sets the value to new_value .

Throws: os_unix_toolkit_error

void V( os_ioctl_t control )

Same as

release(
    1,

control ) .

wait

void wait( os_ioctl_t control )

Same as

obtain(
    1,

control ) .

wait_until_zero

void wait_until_zero( os_ioctl_t control )

Blocks the current process until the value becomes zero. If control (default 0) is set to O_NONBLOCK , does not block but returns an EAGAIN . This function can be recorded.

Throws: os_unix_toolkit_error

sysv_semaphore

Library

Declaration

Options

Interface

Non-Member Functions