Semaphores

Semaphore creation, waiting, signaling, and freeing. More...

Functions
syscall	semcount (semaphore sem)
semaphore	semcreate (int count)
syscall	semfree (semaphore sem)
syscall	signal (semaphore sem)
syscall	signaln (semaphore sem, int count)
syscall	wait (semaphore sem)

Detailed Description

Semaphore creation, waiting, signaling, and freeing.

Function Documentation

syscall semcount

(

semaphore

sem

)

Retrieve a semaphore's count.

Parameters

sem	Semaphore to get the count of.

Returns

On success, returns the semaphore's count; otherwise returns ::SYSERR. This function can only fail if sem did not specify a valid semaphore.

semaphore semcreate

(

int

count

)

Creates a semaphore that initially has the specified count.

Parameters

count

Initial count of the semaphore (often the number of some resource that is available). Must be non-negative.

Returns

On success, returns the new semaphore; otherwise returns ::SYSERR. The new semaphore must be freed with semfree() when no longer needed. This function can only fail if the system is out of semaphores or if count was negative.

syscall semfree

(

semaphore

sem

)

Frees a semaphore. This can be done even if threads are waiting on it, in which case they will be released and able to run. However, be careful, since such threads will return from wait()ing on a semaphore that no longer exists and there may be assumptions that no longer hold.

Parameters

sem	Semaphore to free (allocated by semcreate()).

Returns

::SYSERR if sem did not specify a valid semaphore; otherwise ::OK.

syscall signal

(

semaphore

sem

)

Signal a semaphore, releasing up to one waiting thread.

signal() may reschedule the currently running thread. As a result, signal() should not be called from non-reentrant interrupt handlers unless ::resdefer is set to a positive value at the start of the interrupt handler.

Parameters

sem	Semaphore to signal.

Returns

::OK on success, ::SYSERR on failure. This function can only fail if sem did not specify a valid semaphore.

syscall signaln	(	semaphore	sem,
		int	count
	)

Signal a semaphore count times, releasing count waiting threads.

signaln() may reschedule the currently running thread. As a result, signaln() should not be called from non-reentrant interrupt handlers unless ::resdefer is set to a positive value at the start of the interrupt handler.

Parameters

sem	Semaphore to signal.
count	Number of times to signal, which must be positive.

Returns

::OK on success, ::SYSERR on failure. This function can only fail if sem did not specify a valid semaphore of if count was not positive.

syscall wait

(

semaphore

sem

)

Wait on a semaphore.

If the semaphore's count is positive, it will be decremented and this function will return immediately. Otherwise, the currently running thread will be put to sleep until the semaphore is signaled with signal() or signaln(), or freed with semfree().

Parameters

sem	Semaphore to wait on.

Returns

::OK on success; ::SYSERR on failure. This function can only fail if sem did not specify a valid semaphore.