191 lines
6.1 KiB
C++
191 lines
6.1 KiB
C++
// Copyright (C) 2003 Davis E. King (davis@dlib.net)
|
|
// License: Boost Software License See LICENSE.txt for the full license.
|
|
#undef DLIB_SYNC_EXTENSION_KERNEl_ABSTRACT_
|
|
#ifdef DLIB_SYNC_EXTENSION_KERNEl_ABSTRACT_
|
|
|
|
#include "../threads/threads_kernel_abstract.h"
|
|
#include "../threads/rmutex_extension_abstract.h"
|
|
#include "../threads/rsignaler_extension_abstract.h"
|
|
#include "../algs.h"
|
|
|
|
namespace dlib
|
|
{
|
|
|
|
template <
|
|
typename base
|
|
>
|
|
class sync_extension : public base
|
|
{
|
|
|
|
/*!
|
|
REQUIREMENTS ON base
|
|
base must have a default constructor
|
|
base must implement swap(base&)
|
|
|
|
|
|
WHAT THIS OBJECT REPRESENTS
|
|
This object represents a general extension to any object (given the
|
|
restrictions on base). This object gives any object which it extends
|
|
an integrated rmutex and rsignaler object. The extended object will
|
|
then be able to be treated as if it was also a rmutex and rsignaler.
|
|
|
|
NOTE that just like the threading api, this object does not check
|
|
its requires clauses so be careful with it.
|
|
|
|
Also note that swap() does not swap the rmutex and rsignaler objects.
|
|
the rmutex and rsignaler are associated with the object instance itself,
|
|
not with whatever the object represents.
|
|
!*/
|
|
|
|
|
|
public:
|
|
|
|
sync_extension (
|
|
);
|
|
/*!
|
|
ensures
|
|
- #*this is properly initialized
|
|
throws
|
|
- std::bad_alloc
|
|
this is thrown if there is a problem gathering memory
|
|
- dlib::thread_error
|
|
this is thrown if there is a problem creating threading objects
|
|
- any exception thrown by the constructor for the parent class base
|
|
!*/
|
|
|
|
template <
|
|
typename T
|
|
>
|
|
sync_extension (
|
|
const T& one
|
|
);
|
|
/*!
|
|
ensures
|
|
- #*this is properly initialized
|
|
- the argument one will be passed on to the constructor for the parent
|
|
class base.
|
|
throws
|
|
- std::bad_alloc
|
|
this is thrown if there is a problem gathering memory
|
|
- dlib::thread_error
|
|
this is thrown if there is a problem creating threading objects
|
|
- any exception thrown by the constructor for the parent class base
|
|
!*/
|
|
|
|
template <
|
|
typename T,
|
|
typename U
|
|
>
|
|
sync_extension (
|
|
const T& one,
|
|
const T& two
|
|
);
|
|
/*!
|
|
ensures
|
|
- #*this is properly initialized
|
|
- the argument one will be passed on to the constructor for the parent
|
|
class base as its first argument.
|
|
- the argument two will be passed on to the constructor for the parent
|
|
class base as its second argument.
|
|
throws
|
|
- std::bad_alloc
|
|
this is thrown if there is a problem gathering memory
|
|
- dlib::thread_error
|
|
this is thrown if there is a problem creating threading objects
|
|
- any exception thrown by the constructor for the parent class base
|
|
!*/
|
|
|
|
|
|
const rmutex& get_mutex (
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- returns the rmutex embedded in this object
|
|
!*/
|
|
|
|
void lock (
|
|
) const;
|
|
/*!
|
|
requires
|
|
- the thread calling lock() does not already have a lock on *this
|
|
ensures
|
|
- if (*this is currently locked by another thread) then
|
|
- the thread that called lock() on *this is put to sleep until
|
|
it becomes available
|
|
- if (*this is currently unlocked) then
|
|
- #*this becomes locked and the current thread is NOT put to sleep
|
|
but now "owns" #*this
|
|
!*/
|
|
|
|
void unlock (
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- #*this is unlocked (i.e. other threads may now lock this object)
|
|
!*/
|
|
|
|
|
|
void wait (
|
|
) const;
|
|
/*!
|
|
requires
|
|
- *this is locked and owned by the calling thread
|
|
ensures
|
|
- atomically unlocks *this and blocks the calling thread
|
|
- calling thread will wake if another thread calls signal() or broadcast()
|
|
on *this
|
|
- when wait returns the calling thread again has a lock on #*this
|
|
!*/
|
|
|
|
|
|
bool wait_or_timeout (
|
|
unsigned long milliseconds
|
|
) const;
|
|
/*!
|
|
requires
|
|
- *this is locked and owned by the calling thread
|
|
ensures
|
|
- atomically unlocks *this and blocks the calling thread
|
|
- calling thread will wake if another thread calls signal() or broadcast()
|
|
on *this
|
|
- after the specified number of milliseconds has elapsed the calling thread
|
|
will wake once *this is free to be locked
|
|
- when wait returns the calling thread again has a lock on #*this
|
|
|
|
- returns false if the call to wait_or_timeout timed out
|
|
- returns true if the call did not time out
|
|
!*/
|
|
|
|
void signal (
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- if (at least one thread is waiting on *this) then
|
|
- at least one of the waiting threads will wake
|
|
!*/
|
|
|
|
void broadcast (
|
|
) const;
|
|
/*!
|
|
ensures
|
|
- any and all threads waiting on *this will wake
|
|
!*/
|
|
|
|
};
|
|
|
|
template <
|
|
typename base
|
|
>
|
|
inline void swap (
|
|
sync_extension<base>& a,
|
|
sync_extension<base>& b
|
|
) { a.swap(b); }
|
|
/*!
|
|
provides a global swap function
|
|
!*/
|
|
|
|
}
|
|
|
|
#endif // DLIB_SYNC_EXTENSION_KERNEl_ABSTRACT_
|
|
|