qsem.c File Reference

Semaphore APIs. More...

Go to the source code of this file.

Functions
int	qsem_init (const char *keyfile, int keyid, int nsems, bool recreate)
	Initialize semaphores.
int	qsem_getid (const char *keyfile, int keyid)
	Get the identifier of an existing semaphore set.
bool	qsem_enter (int semid, int semno)
	Lock a semaphore and enter a critical section.
bool	qsem_enter_nowait (int semid, int semno)
	Try to lock a semaphore without waiting.
bool	qsem_enter_force (int semid, int semno, int maxwaitms, bool *forceflag)
	Wait for a semaphore, then force it open if needed.
bool	qsem_leave (int semid, int semno)
	Unlock a semaphore and leave the critical section.
bool	qsem_check (int semid, int semno)
	Get the status of a semaphore.
bool	qsem_free (int semid)
	Release a semaphore set from the system.

Detailed Description

Semaphore APIs.

Note

[daemon main]
#define MAX_SEMAPHORES (2)
 
// create semaphores
int semid = qsem_init("/some/file/for/generating/unique/key", 'q', MAX_SEMAPHORES, true);
if(semid < 0) {
  printf("ERROR: Can't initialize semaphores.\n");
  return -1;
}
 
// fork children
(... child forking codes ...)
 
// at the end of daemon, free semaphores
if(semid >= 0) qsem_free(semid);
 
[forked child]
// critical section for resource 0
qsem_enter(semid, 0);
(... guaranteed as atomic procedure ...)
qsem_leave(semid, 0);
 
(... some codes ...)
 
// critical section for resource 1
qsem_enter(semid, 1);
(... guaranteed as atomic procedure ...)
qsem_leave(semid, 1);
 
[other program which uses resource 1]
int semid = qsem_getid("/some/file/for/generating/unique/key", 'q');
if(semid < 0) {
  printf("ERROR: Can't get semaphore id.\n");
  return -1;
}
 
// critical section for resource 1
qsem_enter(semid, 1);
(... guaranteed as atomic procedure ...)
qsem_leave(semid, 1);

Definition in file qsem.c.

Function Documentation

qsem_init()

int qsem_init	(	const char *	keyfile,
		int	keyid,
		int	nsems,
		bool	recreate )

Initialize semaphores.

Parameters

keyfile	seed used to generate a unique IPC key
keyid	seed used to generate a unique IPC key
nsems	number of semaphores to initialize
recreate	set to true to recreate the semaphore set if it already exists

Returns

non-negative semaphore identifier on success, or -1 on failure.

int semid = qsem_init("/tmp/mydaemon.pid", 'q', 10, true);

Definition at line 102 of file qsem.c.

qsem_getid()

int qsem_getid	(	const char *	keyfile,
		int	keyid )

Get the identifier of an existing semaphore set.

Parameters

keyfile	seed used to generate a unique IPC key
keyid	seed used to generate a unique IPC key

Returns

non-negative semaphore identifier on success, or -1 on failure.

Definition at line 155 of file qsem.c.

qsem_enter()

bool qsem_enter	(	int	semid,
		int	semno )

Lock a semaphore and enter a critical section.

Parameters

semid	semaphore identifier
semno	semaphore number

Returns

true on success, otherwise false.

Note

If the semaphore is already locked, this function waits until it is released.

Definition at line 180 of file qsem.c.

qsem_enter_nowait()

bool qsem_enter_nowait	(	int	semid,
		int	semno )

Try to lock a semaphore without waiting.

Parameters

semid	semaphore identifier
semno	semaphore number

Returns

true on success, or false if it is already locked or an error occurs.

Definition at line 202 of file qsem.c.

qsem_enter_force()

bool qsem_enter_force	(	int	semid,
		int	semno,
		int	maxwaitms,
		bool *	forceflag )

Wait for a semaphore, then force it open if needed.

Parameters

semid	semaphore identifier
semno	semaphore number
maxwaitms	maximum time to wait, in milliseconds
forceflag	status output. This can be NULL if you do not need it.

Returns

true on success, otherwise false.

Note

This function waits up to maxwaitms for the semaphore to be released. If it is released normally in time, forceflag is set to false. If the wait time is exceeded and the semaphore is forcibly released, forceflag is set to true.

Definition at line 232 of file qsem.c.

qsem_leave()

bool qsem_leave	(	int	semid,
		int	semno )

Unlock a semaphore and leave the critical section.

Parameters

semid	semaphore identifier
semno	semaphore number

Returns

true on success, otherwise false.

Definition at line 263 of file qsem.c.

qsem_check()

bool qsem_check	(	int	semid,
		int	semno )

Get the status of a semaphore.

Parameters

semid	semaphore identifier
semno	semaphore number

Returns

true if the semaphore is locked, or false if it is unlocked.

Definition at line 285 of file qsem.c.

qsem_free()

bool qsem_free

(

int

semid

)

Release a semaphore set from the system.

Parameters

semid

semaphore identifier

Returns

true on success, otherwise false.

Definition at line 298 of file qsem.c.