4.24.1 Semaphores interface

Function: sem-open name oflag mode

Function: sem-open name oflag mode value

Interface to the C function sem_open(), see the manual page sem_open(3). Initialise and open a named semaphore using the pathname name. If successful return a pointer object referencing the semaphore, else raise an exception.

oflag must be a fixnum representing a bitwise inclusive OR combination of some of the following values: O_CREAT, O_EXCL, O_RDWR.

mode must be a fixnum representing a bitwise inclusive OR combination of some of the following values:

S_IRUSR   S_IWUSR   S_IXUSR
S_IRGRP   S_IWGRP   S_IXGRP
S_IROTH   S_IWOTH   S_IXOTH

The optional value must be a exact integer in the range of the C language type unsigned int; when not given it defaults to zero.

Named semaphores must be closed with sem-close and removed with sem-unlink.

Function: sem-close sem

Interface to the C function sem_close(), see the manual page sem_close(3). Close the named semaphore referenced by sem, which must be a pointer object; note that the semaphore will continue to exist until sem-unlink is called. If successful return unspecified values, else raise an exception.

Function: sem-unlink name

Interface to the C function sem_unlink(), see the manual page sem_unlink(3). Remove the named semaphore referenced by the pathname name; note that the semaphore name is removed immediately, but the semaphore itself will continue to exist until all the processes referencing it will call sem-close. If successful return unspecified values, else raise an exception.

Function: sizeof-sem_t

Return an exact integer representing the value of the C language expression sizeof(sem_t). This value is needed to allocate enough memory for sem-init to initialise a semaphore structure.

Function: sem-init sem pshared

Function: sem-init sem pshared value

Interface to the C function sem_init(), see the manual page sem_init(3). Initialise an unnamed semaphore; if successful return sem itself, else raise an exception.

sem must be a pointer object referencing a memory region big enough to hold a C language sem_t data structure; such memory region must be allocated in such a way that it can be shared among the entities interested in accessing the semaphore.

pshared is interpreted as a boolean value: when false, the semaphore is meant to be shared among multiple threads in this process; when true, the semaphore is meant to be shared among multiple processes resulting from forking the current process.

The optional value must be an exact integer in the range of the C language type unsigned int: it represents the initial value of the semaphore; when not given: it defaults to zero.

Unnamed semaphores must be finalised with sem-destroy.

Function: sem-destroy sem

Interface to the C function sem_destroy(), see the manual page sem_destroy(3). Finalise the unnamed semaphore referenced by sem, which must be a pointer object; if successful return unspecified values, else raise an exception.

Function: sem-post sem

Interface to the C function sem_post(), see the manual page sem_post(3). Increment (unlock) the unnamed semaphore referenced by sem, which must be a pointer object; if successful return unspecified values, else raise an exception.

Function: sem-wait sem

Interface to the C function sem_wait(), see the manual page sem_wait(3). Decrement (lock) the unnamed semaphore referenced by sem, which must be a pointer object, until the semaphore is unlocked; if successful return unspecified values, else raise an exception.

Function: sem-trywait sem

Interface to the C function sem_trywait(), see the manual page sem_trywait(3). Decrement (lock) the unnamed semaphore referenced by sem, which must be a pointer object; if successful in locking return the boolean #t, if the semaphore is already locked return the boolean #f, else raise an exception.

Function: sem-timedwait sem abs-timeout

Interface to the C function sem_timedwait(), see the manual page sem_timedwait(3). Attempt to decrement (lock) the unnamed semaphore referenced by sem, which must be a pointer object, with a timeout. If successful in locking return the boolean #t; if the semaphore is already locked and it is not unlocked before the timeout expiration: return the boolean #f; else raise an exception.

abs-timeout must be an instance of struct-timespec representing the absolute timeout since the Epoch. struct-timespec

Function: sem-getvalue sem

Interface to the C function sem_getvalue(), see the manual page sem_getvalue(3). Retrieve the current value of the semaphore referenced by sem, which must be a pointer object; if successful return an exact integer representing the value, else raise an exception.