| Home | Libraries | People | FAQ | More

### Mutex Types

##### Class `mutex`

    #include <boost/fiber/mutex.hpp>

    namespace boost {
    namespace fibers {

    class mutex {
    public:
        mutex();
        ~mutex();

        mutex( mutex const& other) = delete;
        mutex & operator=( mutex const& other) = delete;

        void lock();
        bool try_lock();
        void unlock();
    };

    }}

`mutex` provides an exclusive-ownership mutex. At most one fiber can own the lock on a given instance of `mutex` at any time. Multiple concurrent calls to `lock()`, `try_lock()` and `unlock()` shall be permitted.

Any fiber blocked in `lock()` is suspended until the owning fiber releases the lock by calling `unlock()`.

##### Member function `lock`()

    void lock();

Precondition:

  The calling fiber doesn't own the mutex.

Effects:

  The current fiber blocks until ownership can be obtained.

Throws:

  `lock_error`

Error Conditions:

  resource_deadlock_would_occur: if `boost::this_fiber::get_id()` already owns the mutex.

##### Member function `try_lock`()

    bool try_lock();

Precondition:

  The calling fiber doesn't own the mutex.

Effects:

  Attempt to obtain ownership for the current fiber without blocking.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  `lock_error`

Error Conditions:

  resource_deadlock_would_occur: if `boost::this_fiber::get_id()` already owns the mutex.

##### Member function `unlock`()

    void unlock();

Precondition:

  The current fiber owns `*this`.

Effects:

  Releases a lock on `*this` by the current fiber.

Throws:

  `lock_error`

Error Conditions:

  operation_not_permitted: if `boost::this_fiber::get_id()` does not own the mutex.

##### Class `timed_mutex`

    #include <boost/fiber/timed_mutex.hpp>

    namespace boost {
    namespace fibers {

    class timed_mutex {
    public:
        timed_mutex();
        ~timed_mutex();

        timed_mutex( timed_mutex const& other) = delete;
        timed_mutex & operator=( timed_mutex const& other) = delete;

        void lock();
        bool try_lock();
        void unlock();

        template< typename Clock, typename Duration >
        bool try_lock_until( std::chrono::time_point< Clock, Duration > const& timeout_time);
        template< typename Rep, typename Period >
        bool try_lock_for( std::chrono::duration< Rep, Period > const& timeout_duration);
    };

    }}

`timed_mutex` provides an exclusive-ownership mutex. At most one fiber can own the lock on a given instance of `timed_mutex` at any time. Multiple concurrent calls to `lock()`, `try_lock()`, `try_lock_until()`, `try_lock_for()` and `unlock()` shall be permitted.

##### Member function `lock`()

    void lock();

Precondition:

  The calling fiber doesn't own the mutex.

Effects:

  The current fiber blocks until ownership can be obtained.

Throws:

  `lock_error`

Error Conditions:

  resource_deadlock_would_occur: if `boost::this_fiber::get_id()` already owns the mutex.

##### Member function `try_lock`()

    bool try_lock();

Precondition:

  The calling fiber doesn't own the mutex.

Effects:

  Attempt to obtain ownership for the current fiber without blocking.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  `lock_error`

Error Conditions:

  resource_deadlock_would_occur: if `boost::this_fiber::get_id()` already owns the mutex.

##### Member function `unlock`()

    void unlock();

Precondition:

  The current fiber owns `*this`.

Effects:

  Releases a lock on `*this` by the current fiber.

Throws:

  `lock_error`

Error Conditions:

  operation_not_permitted: if `boost::this_fiber::get_id()` does not own the mutex.

##### Templated member function `try_lock_until`()

    template< typename Clock, typename Duration >
    bool try_lock_until( std::chrono::time_point< Clock, Duration > const& timeout_time);

Precondition:

  The calling fiber doesn't own the mutex.

Effects:

  Attempt to obtain ownership for the current fiber. Blocks until ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as `timed_mutex::try_lock()`.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  `lock_error`, timeout-related exceptions.

Error Conditions:

  resource_deadlock_would_occur: if `boost::this_fiber::get_id()` already owns the mutex.

##### Templated member function `try_lock_for`()

    template< typename Rep, typename Period >
    bool try_lock_for( std::chrono::duration< Rep, Period > const& timeout_duration);

Precondition:

  The calling fiber doesn't own the mutex.

Effects:

  Attempt to obtain ownership for the current fiber. Blocks until ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as `timed_mutex::try_lock()`.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  `lock_error`, timeout-related exceptions.

Error Conditions:

  resource_deadlock_would_occur: if `boost::this_fiber::get_id()` already owns the mutex.

##### Class `recursive_mutex`

    #include <boost/fiber/recursive_mutex.hpp>

    namespace boost {
    namespace fibers {

    class recursive_mutex {
    public:
        recursive_mutex();
        ~recursive_mutex();

        recursive_mutex( recursive_mutex const& other) = delete;
        recursive_mutex & operator=( recursive_mutex const& other) = delete;

        void lock();
        bool try_lock() noexcept;
        void unlock();
    };

    }}

`recursive_mutex` provides an exclusive-ownership recursive mutex. At most one fiber can own the lock on a given instance of `recursive_mutex` at any time. Multiple concurrent calls to `lock()`, `try_lock()` and `unlock()` shall be permitted. A fiber that already has exclusive ownership of a given `recursive_mutex` instance can call `lock()` or `try_lock()` to acquire an additional level of ownership of the mutex. `unlock()` must be called once for each level of ownership acquired by a single fiber before ownership can be acquired by another fiber.

##### Member function `lock`()

    void lock();

Effects:

  The current fiber blocks until ownership can be obtained.

Throws:

  Nothing

##### Member function `try_lock`()

    bool try_lock() noexcept;

Effects:

  Attempt to obtain ownership for the current fiber without blocking.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  Nothing.

##### Member function `unlock`()

    void unlock();

Effects:

  Releases a lock on `*this` by the current fiber.

Throws:

  `lock_error`

Error Conditions:

  operation_not_permitted: if `boost::this_fiber::get_id()` does not own the mutex.

##### Class `recursive_timed_mutex`

    #include <boost/fiber/recursive_timed_mutex.hpp>

    namespace boost {
    namespace fibers {

    class recursive_timed_mutex {
    public:
        recursive_timed_mutex();
        ~recursive_timed_mutex();

        recursive_timed_mutex( recursive_timed_mutex const& other) = delete;
        recursive_timed_mutex & operator=( recursive_timed_mutex const& other) = delete;

        void lock();
        bool try_lock() noexcept;
        void unlock();

        template< typename Clock, typename Duration >
        bool try_lock_until( std::chrono::time_point< Clock, Duration > const& timeout_time);
        template< typename Rep, typename Period >
        bool try_lock_for( std::chrono::duration< Rep, Period > const& timeout_duration);
    };

    }}

`recursive_timed_mutex` provides an exclusive-ownership recursive mutex. At most one fiber can own the lock on a given instance of `recursive_timed_mutex` at any time. Multiple concurrent calls to `lock()`, `try_lock()`, `try_lock_for()`, `try_lock_until()` and `unlock()` shall be permitted. A fiber that already has exclusive ownership of a given `recursive_timed_mutex` instance can call `lock()`, `try_lock()`, `try_lock_for()` or `try_lock_until()` to acquire an additional level of ownership of the mutex. `unlock()` must be called once for each level of ownership acquired by a single fiber before ownership can be acquired by another fiber.

##### Member function `lock`()

    void lock();

Effects:

  The current fiber blocks until ownership can be obtained.

Throws:

  Nothing

##### Member function `try_lock`()

    bool try_lock() noexcept;

Effects:

  Attempt to obtain ownership for the current fiber without blocking.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  Nothing.

##### Member function `unlock`()

    void unlock();

Effects:

  Releases a lock on `*this` by the current fiber.

Throws:

  `lock_error`

Error Conditions:

  operation_not_permitted: if `boost::this_fiber::get_id()` does not own the mutex.

##### Templated member function `try_lock_until`()

    template< typename Clock, typename Duration >
    bool try_lock_until( std::chrono::time_point< Clock, Duration > const& timeout_time);

Effects:

  Attempt to obtain ownership for the current fiber. Blocks until ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as `recursive_timed_mutex::try_lock()`.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  Timeout-related exceptions.

##### Templated member function `try_lock_for`()

    template< typename Rep, typename Period >
    bool try_lock_for( std::chrono::duration< Rep, Period > const& timeout_duration);

Effects:

  Attempt to obtain ownership for the current fiber. Blocks until ownership can be obtained, or the specified time is reached. If the specified time has already passed, behaves as `recursive_timed_mutex::try_lock()`.

Returns:

  `true` if ownership was obtained for the current fiber, `false` otherwise.

Throws:

  Timeout-related exceptions.