aboutsummaryrefslogtreecommitdiff
path: root/src/condition.h
blob: 71634f550168b93cafad318954f315c0e6de16d3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
/*
 * Copyright (C) 2007-2011 Xagasoft, All rights reserved.
 *
 * This file is part of the libbu++ library and is released under the
 * terms of the license contained in the file LICENSE.
 */

#ifndef BU_CONDITION_H
#define BU_CONDITION_H

#include <pthread.h>

#include "bu/mutex.h"

namespace Bu
{
	/**
	 * Ito condition.  This is a fairly simple condition mechanism.  As you may
	 * notice this class inherits from the Mutex class, this is because all
	 * conditions must be within a locked block.  The standard usage of a
	 * condition is to pause one thread, perhaps indefinately, until another
	 * thread signals that it is alright to procede.
	 * <br>
	 * Standard usage for the thread that wants to wait is as follows:
	 * <pre>
	 * Condition cond;
	 * ... // Perform setup and enter your run loop
	 * cond.lock();
	 * while( !isFinished() ) // Could be anything you're waiting for
	 *     cond.wait();
	 * ...  // Take care of what you have to.
	 * cond.unlock();
	 * </pre>
	 * The usage for the triggering thread is much simpler, when it needs to
	 * tell the others that it's time to grab some data it calls either signal
	 * or broadcast.  See both of those functions for the difference.
	 *@ingroup Threading
	 */
	class Condition : public Mutex
	{
	public:
		/**
		 * Create a condition.
		 */
		Condition();

		/**
		 * Destroy a condition.
		 */
		~Condition();

		/**
		 * Wait forever, or until signalled.  This has to be called from within
		 * a locked section, i.e. before calling this this object's lock
		 * function should be called.
		 */
		int wait();

		/**
		 * Wait for a maximum of nSec seconds and nUSec micro-seconds or until
		 * signalled.  This is a little more friendly function if you want to
		 * perform other operations in the thrad loop that calls this function.
		 * Like the other wait function, this must be inside a locked section.
		 *@param nSec The seconds to wait.
		 *@param nUSec the micro-seconds to wait.
		 */
		int wait( int nSec, int nUSec );

		/**
		 * Notify the next thread waiting on this condition that they can go
		 * ahead.  This only signals one thread, the next one in the condition
		 * queue, that it is safe to procede with whatever operation was being
		 * waited on.
		 */
		int signal();

		/**
		 * Notify all threads waiting on this condition that they can go ahead
		 * now. This function is slower than signal, but more effective in
		 * certain situations where you may not know how many threads should be
		 * activated.
		 */
		int broadcast();

	private:
		pthread_cond_t cond;	/**< Internal condition reference. */
	};
}

#endif