Класс threads_1::cond_var_t

#include <threads.hpp>

Полный список членов класса

---

Подробное описание

Класс синхронизирующего объекта Condition Variable.

Данный синхронизирующий объект характеризуется тем, что он должен использоваться только вместе с объектом mutex_sem_t.

Принцип работы:

• захватывается mutex_sem;
• начинается ожидание condition_variable;
• во время ожидания mutex_sem освобождается;
• ожидается появление соответствующего сигнала;
• mutex_sem захватывается вновь;
• происходит возврат из ожидания condition_variable.

Внимание:

Перед обращением к методу wait необходимо обязательно предварительно захватить объект-семафор. Метод wait не делает этого сам, т.к. в некоторых случаях между захватом семафора и ожиданием события необходимо выполнить какие-либо действия над данными, защищаемыми данным семафором.

void
read_data()
{
  // Захватывается семафор.
  threads_1::mutex_sem_t::lock_t lock( g_sem );
  // Проверяем наличие данных для чтения.
  // Обращаться к переменной is_data_available
  // можно только при захваченом семафоре g_sem.
  if( !is_data_available )
    // Ожидаем поступления данных.
    // Важно то, что если данные есть, то
    // ожидать наступления события не нужно,
    // но семафор все равно должен быть
    // захвачен.
    g_cond.wait();
  ...
}

Перед обращением к методам notify_one и notify_all нужно обязательно захватить объект-семафор. В противном случае может возникнуть т.н. race condition -- когда нить, ожидающая события не успеет вызвать метод wait, в то время как порождающая событие нить осуществит вызов метода notify_one.

v.1.3

В предшествующих 1.3 версиях объект cond_var_t должен был быть жестко связан с одним объектом mutex_sem_t (ссылка на который передавалась cond_var_t в конструктор). Это делало объект cond_var_t огранниченным по сравнению с понятием condition_variable в POSIX, т.к. в POSIX при ожидании condition-а можно было использовать различные объекты mutex. В версии 1.3 класс cond_var_t сохранил совместимость с предыдущими версиями и получил дополнительные возможности:

• объект cond_var_t можно связать с объектом mutex_sem_t, временем жизни которого будет управлять сам объект cond_var_t. Для захвата и освобождения mutex-a, которым управляет cond_var_t добавлены методы lock, release. Так же объект cond_var_t может передаваться в mutex_sem_t::lock_t. Все это позволяет в большинстве случаев, когда один mutex связан с одним condition_variable обходиться только одним объектом cond_variable_t.

  cond_var_t g_cond( &cond_var_t::own_mutex );
  void
  read_data()
  {
    // Захватывается семафор.
    threads_1::mutex_sem_t::lock_t lock( g_cond );
    // Проверяем наличие данных для чтения.
    // Обращаться к переменной is_data_available
    // можно только при захваченом семафоре g_sem.
    if( !is_data_available )
      // Ожидаем поступления данных.
      // Важно то, что если данные есть, то
      // ожидать наступления события не нужно,
      // но семафор все равно должен быть
      // захвачен.
      g_cond.wait();
    ...
  }
  

• добавлен метод wait( const mutex_sem_t & ) в который можно передать ссылку на любой mutex_sem_t. Т.е. cond_var_t становиться аналогом condition_variable из POSIX;
• добавлен конструктор без параметров. Он предназначен для случаев, когда будет использоваться только метод wait( const mutex_sem_t & ). При обращении к любому из методов, требующих наличия связанного с cond_var_t объекта mutex_sem_t порождается исключение std::runtime_error.

Примеры:

sample/cond_var/main.cpp, sample/cond_var_2/main.cpp, sample/cond_var_3/main.cpp, sample/cond_var_4/main.cpp и sample/simple_proc/main.cpp.

Открытые члены
	cond_var_t ()
	Конструктор по-умолчанию.
	cond_var_t (mutex_sem_t *(*mutex_creator)())
	Конструктор для создания собственного объекта mutex_sem_t.
	cond_var_t (mutex_sem_t &sem)
void	wait () const
	Ожидать condition_variable.
void	wait (const mutex_sem_t &) const
	Ожидать с использованием указанного семафора.
	operator const mutex_sem_t & () const
	Позволяет использовать объект cond_var_t в качестве параметра конструктора mutex_sem_t::lock_t.
void	lock () const
	Захватить семафор с которым связан объект.
void	release () const
	Освободить семафор с которым связан объект.
void	notify_one ()
	Запустить один процесс, ожидающий condition_variable.
void	notify_all ()
	Запустить все процессы, ожидающие condition_variable.
Открытые статические члены
mutex_sem_t *	own_mutex ()
	Создатель подчиненных объектов mutex_sem_t.
Защищенные данные
mutex_sem_t *	m_sem
	Семафор, который используется для предотвращения т.н. race conditions.
_os_cond_var_t *	m_cv
bool	m_is_own_mutex
	Владеем ли мы объектом mutex_sem_t?

---

Конструктор(ы)

threads_1::cond_var_t::cond_var_t (   )

Конструктор по-умолчанию. Начиная с: v.1.3 Подразумевает, что пользователь класса будет работать только с методом wait( const mutex_sem_t & ) и не будет обращаться к другим методам.

threads_1::cond_var_t::cond_var_t (  mutex_sem_t *(*  mutex_creator)()  )

Конструктор для создания собственного объекта mutex_sem_t. Начиная с: v.1.3 Позволяет работать только с одним объектом cond_var_t не создавая явно отдельного объекта mutex_sem_t. Аргументы: mutex_creator  Функция, которая должна возвращать динамически созданный объект mutex_sem_t.

threads_1::cond_var_t::cond_var_t (  mutex_sem_t &  sem  )

Аргументы: sem  Семафор, который используется для предотвращения т.н. race conditions

---

Методы

void threads_1::cond_var_t::lock (   )  const

Захватить семафор с которым связан объект. Начиная с: v.1.3 Исключения: std::exception  Если объект не связан с семафором.

void threads_1::cond_var_t::notify_all (   )

Запустить все процессы, ожидающие condition_variable. Если никто не ждет, то событие считается сработавшим впустую. Примеры: sample/cond_var/main.cpp.

void threads_1::cond_var_t::notify_one (   )

Запустить один процесс, ожидающий condition_variable. Если никто не ждет, то событие считается сработавшим впустую. Примеры: sample/cond_var/main.cpp и sample/simple_proc/main.cpp.

threads_1::cond_var_t::operator const mutex_sem_t & (   )  const

Позволяет использовать объект cond_var_t в качестве параметра конструктора mutex_sem_t::lock_t. Начиная с: v.1.3 Внимание: Будет порождать исключение std::exception, если использовался конструктор по-умолчанию.

mutex_sem_t * threads_1::cond_var_t::own_mutex (   )  [static]

Создатель подчиненных объектов mutex_sem_t. Начиная с: v.1.3 Предназначен для использования как параметра в конструкторе, требующем указатель на функцию. Возвращает: Указатель на динамически созданный объект, который должен быть уничтожен посредством delete.

void threads_1::cond_var_t::release (   )  const

Освободить семафор с которым связан объект. Начиная с: v.1.3 Исключения: std::exception  Если объект не связан с семафором.

void threads_1::cond_var_t::wait (  const mutex_sem_t &   )  const

Ожидать с использованием указанного семафора. Начиная с: v.1.3 Внимание: Семафор должен быть предварительно захвачен.

void threads_1::cond_var_t::wait (   )  const

Ожидать condition_variable. Внимание: Будет порождать исключение std::exception, если использовался конструктор по-умолчанию. Примеры: sample/simple_proc/main.cpp.

---

Данные класса

bool threads_1::cond_var_t::m_is_own_mutex [protected]

Владеем ли мы объектом mutex_sem_t? Начиная с: v.1.3

mutex_sem_t* threads_1::cond_var_t::m_sem [protected]

Семафор, который используется для предотвращения т.н. race conditions. Может содержать 0, что означает, что пользователь cond_var_t может использовать разные объекты mutex_sem_t при обращении к wait.

---

Объявления и описания членов классов находятся в файлах:

• threads_1/h/threads.hpp
• threads_1/threads.cpp

---