Rudiments
Public Member Functions | Static Public Member Functions | List of all members
semaphoreset Class Reference

Public Member Functions

 semaphoreset ()
 
 ~semaphoreset ()
 
bool supportsTimedSemaphoreOperations ()
 
bool supportsUndoSemaphoreOperations ()
 
bool create (key_t key, mode_t permissions, int32_t semcount, const int32_t *values)
 
bool attach (key_t key, int32_t semcount)
 
bool createOrAttach (key_t key, mode_t permissions, int32_t semcount, const int32_t *values)
 
void dontRemove ()
 
bool forceRemove ()
 
int32_t getId () const
 
bool wait (int32_t index)
 
bool wait (int32_t index, int32_t seconds, int32_t nanoseconds)
 
bool signal (int32_t index)
 
bool waitWithUndo (int32_t index)
 
bool waitWithUndo (int32_t index, int32_t seconds, int32_t nanoseconds)
 
bool signalWithUndo (int32_t index)
 
bool setValue (int32_t index, int32_t value)
 
int32_t getValue (int32_t index)
 
bool setUserName (const char *username)
 
bool setGroupName (const char *groupname)
 
bool setUserId (uid_t uid)
 
bool setGroupId (gid_t gid)
 
bool setPermissions (mode_t permissions)
 
const char * getUserName ()
 
const char * getGroupName ()
 
uid_t getUserId ()
 
gid_t getGroupId ()
 
mode_t getPermissions ()
 
int32_t getWaitingForZero (int32_t index)
 
int32_t getWaitingForIncrement (int32_t index)
 
void retryInterruptedOperations ()
 
void dontRetryInterruptedOperations ()
 

Static Public Member Functions

static bool supported ()
 

Detailed Description

Semaphores allow processes to synchronize their activities.

A semaphore is just a number with two primary operations that can be performed on it: signal() and wait()

The operations are analagous to:

int32_t semaphore;

void signal() { semaphore++; // increment the semaphore }

void wait() { while (semaphore<=0); // wait until the semaphore>0 semaphore–; // decrement the semaphore }

The actual signal() and wait() operations are atomic. There is no chance of another process getting context-switched in and changing the semaphore value between the two lines of code in the wait() process.

Semaphores can be initialized to any number.

The initial value of the semaphore corresponds to the number of processes that will pass directly through their wait() calls without being blocked.

Processes that get blocked calling wait() are placed in a queue. When another process calls signal(), the process at the head of the queue is unblocked.

A semaphoreset is just a collection of related semaphores.

A semaphoreset is owned by a user and group and has access permissions just like a file.

Constructor & Destructor Documentation

◆ semaphoreset()

semaphoreset::semaphoreset ( )

Creates an instance of the semaphoreset class.

◆ ~semaphoreset()

semaphoreset::~semaphoreset ( )

Deletes this instance of the semaphoreset class. Removes the semaphoreset if it was created by this class. If it was only attached to, it is not removed.

Member Function Documentation

◆ attach()

bool semaphoreset::attach ( key_t  key,
int32_t  semcount 
)

Attaches to an already existing semaphore set identified by "key", containing "semcount" semaphores.

◆ create()

bool semaphoreset::create ( key_t  key,
mode_t  permissions,
int32_t  semcount,
const int32_t *  values 
)

Creates a semaphore set identified by "key" containing "semcount" semaphores. "key" should be generated using the ftok function. "permissions" sets the access permissions for the set. "values" should be an array of starting values for each of the semaphores in the set.

◆ createOrAttach()

bool semaphoreset::createOrAttach ( key_t  key,
mode_t  permissions,
int32_t  semcount,
const int32_t *  values 
)

Attempts to create the semaphore set identified by "key". If this fails, it attempts to attach to a semaphore set identified by "key".

◆ dontRemove()

void semaphoreset::dontRemove ( )

Instructs the destructor not to remove the semaphore set if it was created during a call to create() or createOrAttach(). This is useful if an application creates a semaphore set then forks and wants to delete the semaphore set in the forked process but does not want the semaphore removed from the system.

◆ dontRetryInterruptedOperations()

void semaphoreset::dontRetryInterruptedOperations ( )

Causes operations not to automatically be retired if interrupted by a signal. The default is to retry automatically.

◆ forceRemove()

bool semaphoreset::forceRemove ( )

Instructs the destructor to remove the semaphore set, whether it was created or attached to.

◆ getGroupId()

gid_t semaphoreset::getGroupId ( )

Returns the group id of the group that owns this semaphore set.

◆ getGroupName()

const char* semaphoreset::getGroupName ( )

Returns the name of the group that owns this semaphore set

Note that this method allocates a buffer internally and returns it. The calling program must deallocate this buffer.

Note that getGroupName() uses the groupentry class. If you are using this method in a multithreaded application, you may need to supply the groupentry class a mutex. See groupentry.h for more detail.

◆ getId()

int32_t semaphoreset::getId ( ) const

Returns the internal id for the semaphore set.

◆ getPermissions()

mode_t semaphoreset::getPermissions ( )

Returns the access permissions for this semaphore set.

◆ getUserId()

uid_t semaphoreset::getUserId ( )

Returns the user id of the user that owns this semaphore set.

◆ getUserName()

const char* semaphoreset::getUserName ( )

Returns the name of the user that owns this semaphore set.

Note that this method allocates a buffer internally and returns it. The calling program must deallocate this buffer.

Note that getUserName() uses the userentry class. If you are using this method in a multithreaded application, you may need to supply the userentry class a mutex. See userentry.h for more detail.

◆ getValue()

int32_t semaphoreset::getValue ( int32_t  index)

Return the value of the "index"'th semaphore in the set.

◆ getWaitingForIncrement()

int32_t semaphoreset::getWaitingForIncrement ( int32_t  index)

Returns the number of processes that are waiting for the semaphore to increment.

◆ getWaitingForZero()

int32_t semaphoreset::getWaitingForZero ( int32_t  index)

Returns the number of processes that are waiting for the semaphore to become 0.

◆ retryInterruptedOperations()

void semaphoreset::retryInterruptedOperations ( )

Causes operations to automatically be retired if interrupted by a signal. This is the default behiavior.

◆ setGroupId()

bool semaphoreset::setGroupId ( gid_t  gid)

Makes this semaphore set owned by the group identified by "gid".

◆ setGroupName()

bool semaphoreset::setGroupName ( const char *  groupname)

Makes this semaphore set owned by the group "groupname".

Note that setGroupName() uses the groupentry class. If you are using this method in a multithreaded application, you may need to supply the groupentry class a mutex. See groupentry.h for more detail.

◆ setPermissions()

bool semaphoreset::setPermissions ( mode_t  permissions)

Sets the access permissions for this semaphore set to "permissions".

◆ setUserId()

bool semaphoreset::setUserId ( uid_t  uid)

Makes this semaphore set owned by the user identified by "uid".

◆ setUserName()

bool semaphoreset::setUserName ( const char *  username)

Makes this semaphore set owned by the user "username".

Note that setUserName() uses the userentry class. If you are using this method in a multithreaded application, you may need to supply the userentry class a mutex. See userentry.h for more detail.

◆ setValue()

bool semaphoreset::setValue ( int32_t  index,
int32_t  value 
)

Set the "index"'th semaphore in the set to "value".

◆ signal()

bool semaphoreset::signal ( int32_t  index)

Signal on the "index"'th semaphore in the set.

◆ signalWithUndo()

bool semaphoreset::signalWithUndo ( int32_t  index)

Signal on the "index"'th semaphore in the set and undo the signal when the program exits.

◆ supported()

static bool semaphoreset::supported ( )
static

Returns true if the platform supports semaphores and false otherwise.

◆ supportsTimedSemaphoreOperations()

bool semaphoreset::supportsTimedSemaphoreOperations ( )

Returns true if the system supports timed semaphore operations or false otherwise.

◆ supportsUndoSemaphoreOperations()

bool semaphoreset::supportsUndoSemaphoreOperations ( )

Returns true if the system supports the variants of the semaphore operations below with Undo in the method names or false otherwise. On platforms that don't support Undo, the methods below just pass through to non-Undo variants.

◆ wait() [1/2]

bool semaphoreset::wait ( int32_t  index)

Wait on the "index"'th semaphore in the set.

◆ wait() [2/2]

bool semaphoreset::wait ( int32_t  index,
int32_t  seconds,
int32_t  nanoseconds 
)

Wait on the "index"'th semaphore in the set until "seconds" and "nanoseconds" elapse. If both "seconds" and "nanoseconds" are 0 then the wait falls through immediately unless the semaphore had already been signaled. If either "seconds" or "nanoseconds" are negative then the timeout is ignored. Returns false and sets errno to EAGAIN if a timeout occurs. Returns false if the system doesn't support timed semaphore operations.

◆ waitWithUndo() [1/2]

bool semaphoreset::waitWithUndo ( int32_t  index)

Wait on the "index"'th semaphore in the set and undo the wait when the program exits.

◆ waitWithUndo() [2/2]

bool semaphoreset::waitWithUndo ( int32_t  index,
int32_t  seconds,
int32_t  nanoseconds 
)

Wait on the "index"'th semaphore in the set until "seconds" and "nanoseconds" elapse. If both "seconds" and "nanoseconds" are 0 then the wait falls through immediately unless the semaphore had already been signaled. If either "seconds" or "nanoseconds" are negative then the timeout is ignored. Undo the wait when the program exits. Returns false and sets errno to EAGAIN if a timeout occurs. Returns false if the system doesn't support timed semaphore operations.