| Home | Libraries | People | FAQ | More

## Class named_semaphore

boost::interprocess::named_semaphore

## Synopsis

    // In header: <boost/interprocess/sync/named_semaphore.hpp>

    class named_semaphore {
    public:

      // public member functions
      named_semaphore(create_only_t, const char *, unsigned int,
                      const permissions & = permissions());
      named_semaphore(open_or_create_t, const char *, unsigned int,
                      const permissions & = permissions());
      named_semaphore(open_only_t, const char *);
      named_semaphore(create_only_t, const wchar_t *, unsigned int,
                      const permissions & = permissions());
      named_semaphore(open_or_create_t, const wchar_t *, unsigned int,
                      const permissions & = permissions());
      named_semaphore(open_only_t, const wchar_t *);
      ~named_semaphore();
      void post();
      void wait();
      bool try_wait();
      template<typename TimePoint> bool timed_wait(const TimePoint &);

      // public static functions
      static bool remove(const char *);
      static bool remove(const wchar_t *);
    };

## Description

A semaphore with a global name, so it can be found from different processes. Allows several resource sharing patterns and efficient acknowledgment mechanisms.

### `named_semaphore` public member functions

1.     named_semaphore(create_only_t, const char * name, unsigned int initialCount,
                       const permissions & perm = permissions());

   Creates a global semaphore with a name, and an initial count. If the semaphore can't be created throws interprocess_exception

2.     named_semaphore(open_or_create_t, const char * name,
                       unsigned int initialCount,
                       const permissions & perm = permissions());

   Opens or creates a global semaphore with a name, and an initial count. If the semaphore is created, this call is equivalent to named_semaphore(create_only_t, ...) If the semaphore is already created, this call is equivalent to named_semaphore(open_only_t, ... ) and initialCount is ignored.

3.     named_semaphore(open_only_t, const char * name);

   Opens a global semaphore with a name if that semaphore is previously. created. If it is not previously created this function throws interprocess_exception.

4.     named_semaphore(create_only_t, const wchar_t * name,
                       unsigned int initialCount,
                       const permissions & perm = permissions());

   Creates a global semaphore with a name, and an initial count. If the semaphore can't be created throws interprocess_exception

   Note: This function is only available on operating systems with native wchar_t APIs (e.g. Windows).

5.     named_semaphore(open_or_create_t, const wchar_t * name,
                       unsigned int initialCount,
                       const permissions & perm = permissions());

   Opens or creates a global semaphore with a name, and an initial count. If the semaphore is created, this call is equivalent to named_semaphore(create_only_t, ...) If the semaphore is already created, this call is equivalent to named_semaphore(open_only_t, ... ) and initialCount is ignored.

   Note: This function is only available on operating systems with native wchar_t APIs (e.g. Windows).

6.     named_semaphore(open_only_t, const wchar_t * name);

   Opens a global semaphore with a name if that semaphore is previously. created. If it is not previously created this function throws interprocess_exception.

   Note: This function is only available on operating systems with native wchar_t APIs (e.g. Windows).

7.     ~named_semaphore();

   Destroys *this and indicates that the calling process is finished using the resource. The destructor function will deallocate any system resources allocated by the system for use by this process for this resource. The resource can still be opened again calling the open constructor overload. To erase the resource from the system use remove().

8.     void post();

   Increments the semaphore count. If there are processes/threads blocked waiting for the semaphore, then one of these processes will return successfully from its wait function. If there is an error an interprocess_exception exception is thrown.

9.     void wait();

   Decrements the semaphore. If the semaphore value is not greater than zero, then the calling process/thread blocks until it can decrement the counter. If there is an error an interprocess_exception exception is thrown.

10.     bool try_wait();

    Decrements the semaphore if the semaphore's value is greater than zero and returns true. If the value is not greater than zero returns false. If there is an error an interprocess_exception exception is thrown.

11.     template<typename TimePoint> bool timed_wait(const TimePoint & abs_time);

    Decrements the semaphore if the semaphore's value is greater than zero and returns true. Otherwise, waits for the semaphore to the posted or the timeout expires. If the timeout expires, the function returns false. If the semaphore is posted the function returns true. If there is an error throws sem_exception

### `named_semaphore` public static functions

1.     static bool remove(const char * name);

   Erases a named semaphore from the system. Returns false on error. Never throws.

2.     static bool remove(const wchar_t * name);

   Erases a named semaphore from the system. Returns false on error. Never throws.

   Note: This function is only available on operating systems with native wchar_t APIs (e.g. Windows).