1 // ============================================================================
2 // Copyright (c) 2009-2010 Faustino Frechilla
3 // All rights reserved.
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are met:
8 // 1. Redistributions of source code must retain the above copyright notice,
9 // this list of conditions and the following disclaimer.
10 // 2. Redistributions in binary form must reproduce the above copyright
11 // notice, this list of conditions and the following disclaimer in the
12 // documentation and/or other materials provided with the distribution.
13 // 3. The name of the author may not be used to endorse or promote products
14 // derived from this software without specific prior written permission.
16 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 // POSSIBILITY OF SUCH DAMAGE.
28 /// @file q_blocking_queue.h
29 /// @brief Definition of a thread-safe queue based on glib system calls
30 /// It internally contains a std::queue which is protected from concurrent
31 /// access by glib mutextes and conditional variables
33 /// @author Faustino Frechilla
36 /// Faustino Frechilla 04-May-2009 Original development (based on pthreads)
37 /// Faustino Frechilla 19-May-2010 Ported to glib. Removed pthread dependency
40 // ============================================================================
42 #ifndef _GBLOCKINGQUEUE_H_
43 #define _GBLOCKINGQUEUE_H_
47 #include <limits> // std::numeric_limits<>::max
49 #define BLOCKING_QUEUE_DEFAULT_MAX_SIZE std::numeric_limits<std::size_t >::max()
51 /// @brief blocking thread-safe queue
52 /// It uses a mutex+condition variables to protect the internal queue
53 /// implementation. Inserting or reading elements use the same mutex
58 BlockingQueue(std::size_t a_maxSize = BLOCKING_QUEUE_DEFAULT_MAX_SIZE);
61 /// @brief Check if the queue is empty
62 /// This call can block if another thread owns the lock that protects the
64 /// @return true if the queue is empty. False otherwise
67 /// @brief inserts an element into queue queue
68 /// This call can block if another thread owns the lock that protects the
69 /// queue. If the queue is full The thread will be blocked in this queue
70 /// until someone else gets an element from the queue
71 /// @param element to insert into the queue
72 /// @return True if the elem was successfully inserted into the queue.
74 bool Push(const T &a_elem);
76 /// @brief inserts an element into queue queue
77 /// This call can block if another thread owns the lock that protects the
78 /// queue. If the queue is full The call will return false and the element
80 /// @param element to insert into the queue
81 /// @return True if the elem was successfully inserted into the queue.
83 bool TryPush(const T &a_elem);
85 /// @brief extracts an element from the queue (and deletes it from the q)
86 /// If the queue is empty this call will block the thread until there is
87 /// something in the queue to be extracted
88 /// @param a reference where the element from the queue will be saved to
89 void Pop(T &out_data);
91 /// @brief extracts an element from the queue (and deletes it from the q)
92 /// This call gets the block that protects the queue. It will extract the
93 /// element from the queue only if there are elements in it
94 /// @param reference to the variable where the result will be saved
95 /// @return True if the element was retrieved from the queue.
96 /// False if the queue was empty
97 bool TryPop(T &out_data);
99 /// @brief extracts an element from the queue (and deletes it from the q)
100 /// If the queue is empty this call will block the thread until there
101 /// is something in the queue to be extracted or until the timer
102 /// (2nd parameter) expires
103 /// @param reference to the variable where the result will be saved
104 /// @param microsecondsto wait before returning if the queue was empty
105 /// @return True if the element was retrieved from the queue.
106 /// False if the timeout was reached
107 bool TimedWaitPop(T &data, glong microsecs);
110 std::queue<T> m_theQueue;
111 /// maximum number of elements for the queue
112 std::size_t m_maximumSize;
113 /// Mutex to protect the queue
115 /// Conditional variable to wake up threads
119 // include the implementation file
120 #include "g_blocking_queue_impl.h"
122 #endif /* _GBLOCKINGQUEUE_H_ */