Rudiments: semaphoreset Class Reference

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.