The qDecoder Project

qSem.c File Reference

Semaphore Handling API. More...


Functions

int qSemInit (const char *keyfile, int keyid, int nsems, bool ifexistdestroy)
 Initialize semaphore.
int qSemGetId (const char *keyfile, int keyid)
 Get semaphore identifier by keyfile and keyid for the existing semaphore.
bool qSemEnter (int semid, int semno)
 Turn on the flag of semaphore then entering critical section.
bool qSemEnterNowait (int semid, int semno)
 Try to turn on the flag of semaphore.
bool qSemEnterForce (int semid, int semno, int maxwaitms, bool *forceflag)
 Force to turn on the flag of semaphore.
bool qSemLeave (int semid, int semno)
 Turn off the flag of semaphore then leaving critical section.
bool qSemCheck (int semid, int semno)
 Get the status of semaphore.
bool qSemFree (int semid)
 Release semaphore to system.


Detailed Description

Semaphore Handling API.

Note:
   [daemon main]
   #define MAX_SEMAPHORES (2)

   // create semaphores
   int semid = qSemInit("/some/file/for/generating/unique/key", 'q', MAX_SEMAPHORES, true);
   if(semid < 0) {
     printf("ERROR: Can't initialize semaphores.\n");
     return -1;
   }

   // fork childs
   (... child forking codes ...)

   // at the end of daemon, free semaphores
   if(semid >= 0) qSemFree(semid);

   [forked child]
   // critical section for resource 0
   qSemEnter(0);
   (... guaranteed as atomic procedure ...)
   qSemLeave(0);

   (... some codes ...)

   // critical section for resource 1
   qSemEnter(1);
   (... guaranteed as atomic procedure ...)
   qSemLeave(1);

   [other program which uses resource 1]
   int semid = qSemGetId("/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
   qSemEnter(1);
   (... guaranteed as atomic procedure ...)
   qSemLeave(1);

Function Documentation

int qSemInit ( const char *  keyfile,
int  keyid,
int  nsems,
bool  ifexistdestroy 
)

Initialize semaphore.

Parameters:
keyfile seed for generating unique IPC key
keyid seed for generating unique IPC key
nsems number of semaphore to initialize
ifexistdestroy set to true to destroy if semaphore already exists
Returns:
non-negative shared memory identifier if successful, otherwise returns -1

int qSemGetId ( const char *  keyfile,
int  keyid 
)

Get semaphore identifier by keyfile and keyid for the existing semaphore.

Parameters:
keyfile seed for generating unique IPC key
keyid seed for generating unique IPC key
Returns:
non-negative shared memory identifier if successful, otherwise returns -1

bool qSemEnter ( int  semid,
int  semno 
)

Turn on the flag of semaphore then entering critical section.

Parameters:
semid semaphore identifier
semno semaphore number
Returns:
true if successful, otherwise returns false
Note:
If the semaphore is already turned on, this will wait until released

bool qSemEnterNowait ( int  semid,
int  semno 
)

Try to turn on the flag of semaphore.

If it is already turned on, do not wait.

Parameters:
semid semaphore identifier
semno semaphore number
Returns:
true if successful, otherwise(already turned on by other) returns false

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

Force to turn on the flag of semaphore.

Parameters:
semid semaphore identifier
semno semaphore number
maxwaitms maximum waiting micro-seconds to release
forceflag status will be stored, it can be NULL if you don't need this information
Returns:
true if successful, otherwise returns false
Note:
This will wait the semaphore to be released with in maxwaitms. If it it released by locker normally with in maxwaitms, forceflag will be set to false. But if maximum maxwaitms is exceed and the semaphore is released forcely, forceflag will be set to true.

bool qSemLeave ( int  semid,
int  semno 
)

Turn off the flag of semaphore then leaving critical section.

Parameters:
semid semaphore identifier
semno semaphore number
Returns:
true if successful, otherwise returns false

bool qSemCheck ( int  semid,
int  semno 
)

Get the status of semaphore.

Parameters:
semid semaphore identifier
semno semaphore number
Returns:
true for the flag on, false for the flag off

bool qSemFree ( int  semid  ) 

Release semaphore to system.

Parameters:
semid semaphore identifier
Returns:
true if successful, otherwise returns false


[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]