The qDecoder Project: C/C++ Library

- Main Page
- Data Structures
- Files

- File List
- Globals

# 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]