Inherits object.
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 | setRemove (bool remove) |
| bool | getRemove () |
| int32_t | getId () |
| 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 | setRetryInterruptedOperations (bool retry) |
| bool | getRetryInterruptedOperations () |
 Public Member Functions inherited from object | |
| virtual | ~object () |
Static Public Member Functions | |
| static bool | isSupported () |
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".
◆ 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 | ( | ) |
Returns the internal id for the semaphore set.
◆ getPermissions()
| mode_t semaphoreset::getPermissions | ( | ) |
Returns the access permissions for this semaphore set.
◆ getRemove()
| bool semaphoreset::getRemove | ( | ) |
Returns true if the semaphore will be removed by the destructor and false otherwise.
◆ getRetryInterruptedOperations()
| bool semaphoreset::getRetryInterruptedOperations | ( | ) |
Returns true if interrupted semaphore operations will be retried automatically and false otherwise.
◆ 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 | ) |
Returns 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.
◆ isSupported()
|
static |
Returns true if the platform supports semaphores and false otherwise.
◆ 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".
◆ setRemove()
| void semaphoreset::setRemove | ( | bool | remove | ) |
By default, the destructor will remove a semaphore set if it was created during a call to create() or createOrAttach().
This method allows you to manually override that behavior.
If "remove" is true then the destructor will remove the semaphore set whehter it was created or not. If "remove" is set false then the destructor will not remove the semaphore set, even if it was created.
Manually setting "remove" false is useful, for example, 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.
Manually setting "remove" true is useful, for example, if you want to create a utility for removing arbitray sempahores.
◆ setRetryInterruptedOperations()
| void semaphoreset::setRetryInterruptedOperations | ( | bool | retry | ) |
If "retry" is true then a semaphore operation will be automatically retried if it is interrupted by a signal. If "retry" is false then, if a semaphoore operation is interrupted by a signal, it will fail and the system error will be set to EINTR.
Defaults to true.
◆ 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.
◆ 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.
