NAME

SYNOPSIS

#include <mba/svsem.h>


int svsem_create(svsem_t *sem, int value, int undo);


int svsem_destroy(svsem_t *sem);


int svsem_open(svsem_t *sem, const char *path, int oflag, ... /* mode_t mode, int value */);


int svsem_close(svsem_t *sem);


int svsem_remove(svsem_t *sem);


int svsem_pool_create(struct pool *p,
            unsigned int max_size,
            unsigned int value,
            int undo,
            struct allocator *al);


int svsem_pool_destroy(struct pool *p);

int svsem_wait(svsem_t *sem);


int svsem_trywait(svsem_t *sem);


int svsem_post(svsem_t *sem);


int svsem_post_multiple(svsem_t *sem, int count);


int svsem_getvalue(svsem_t *sem, int *value);


int svsem_setvalue(svsem_t *sem, int value);

DESCRIPTION

The svsem(3m) module is not available in the Win32 environment.

create

The svsem_create function will created a file using mkstemp(3) with a template of /tmp/svsemXXXXXX to generate a semaphore key, create and initialize a semaphore sem and set it's initial value to value. If undo is non-zero, the SEM_UNDO flag for semop calls will be used. The undo parameter should be non-zero for semaphores for which wait and post will be called symmetrically in any process such as binary semaphores. The undo flag must be zero if a process will call wait and post an un-equal number of times such as with counting semaphores.

destroy

The svsem_destroy function destroys the semaphore sem by removing the semaphore set identifier and unlinking the associated file.

open

The svsem_open function creates a new named semaphore or opens an existing semaphore. The path parameter is a path (which must refer to an existing, accessible file) that identifies the target semaphore. The oflag paremeter can be any combination of 0, O_CREAT, O_EXCL, and O_UNDO or'd together although O_EXCL is only meaningful when used with O_CREAT. If O_CREAT is specified two additional parameters are required;

a mode_t parameter specifying the open mode (e.g. 0600) and
an int parameter specifying the initial value of the semaphore (e.g. 1 for a binary semaphore).

If O_CREAT is specified without O_EXCL the semaphore is created and initialized with the specified value if it does not already exist. If the semaphore already exists it is simply opened. Use the O_UNDO flag to specify that SEM_UNDO behavior should be used (recommended unless calls to wait/post are not symetric per process).

Note: It appears that trying to open an existing semaphore on Mac OS X will deadlock because Darwin is not initializing sem_otime properly. This requires futher investigation.

close

The svsem_close function does nothing but release the memory attributed to sem.

remove

The svsem_remove function removes the semaphore identified by sem. Any attempt to access this semaphore after it has been remove will result in all operations returning an error of EIDRM.

pool_create

The svsem_pool_create function will create a pool of semaphores. A file will be created using mkstemp(3) with a template of /tmp/svsemXXXXXX, a semaphore array of max_size will be created and all semaphores will be initialized to the specified value. No initial svsem(3m) objects are created. The pool(3m) functions are used to manage the pool. The pool_get function will return a semaphore initialized to value (reused semaphores will be explicitly reset). The svsem_pool_destroy function must be used to destroy an svsem(3m) pool.

pool_destroy

The svsem_pool_destroy function releases memory associated with the pool, removes the pool semaphore array and unlinks the file backing the array.

wait

The svsem_wait function tests the value of the semaphore identified by sem and does one of two things;

If the value is greater than 0, the value is decremented by 1 and the function returns immediately.
If the value is 0 the calling thread will sleep until svsem_post is called on the semaphore at which point the value will be tested again.

trywait

The svsem_trywait function tests the value of the semaphore identified by sem and does one of two things;

If the value is greater than 0, the value is decremented by 1 and the function returns immediately.
If the value is 0 the call will return -1 and set errno to EAGAIN.

This mechanism can be used to test if a thread will wait.

post

The svsem_post function increments the value of the semaphore identified by sem by 1 and wakes up a thread blocked in svsem_wait if there is one.

post_multiple

The svsem_post_multiple function performs the equivalent of multiple distinct svsem_post operations. The count parameter specifies how many post operations are performed.

getvalue

The svsem_getvalue function stores the value of the semaphore sem into value.

setvalue

The svsem_setvalue function sets the current value of the semaphore to the specified value.

RETURNS

create

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

destroy

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately. Errors that occur attempting to unlink(3m) the associated file are ignored.

open

The svsem_open function returns 0 if the new semaphore was created successfully or NULL if an error occurs in which case errno will be set appropriately. If O_EXCL is specified and the semaphore already exists, NULL is returned and errno is set to EEXIST.

close

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

remove

The svsem_remove function returns 0 if the operation was successful or -1 if an error occured in which case errno will be set appropriately.

pool_create

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

pool_destroy

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

wait

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

trywait

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

post

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

post_multiple

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

getvalue

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

setvalue

If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.