JeVois  1.3
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
BoundedBuffer.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 #pragma once
19 
20 #include <jevois/Types/Semaphore.H>
21 #include <queue>
22 
23 namespace jevois
24 {
25  //! Thread-safe synchronized producer/consumer queue
26  /*! BoundedBuffer is designed for use in producer/consumer scenarios where multiple threads wish to push and pop data
27  onto/from the buffer asynchronously. Threads that try to pop data when the buffer is empty will either sleep
28  until data is actually available or get an exception (depending on template args), and threads that try to push
29  data when the buffer is full will either block until some space is available in the buffer or get an exception
30  (depending on template args).
31 
32  @tparam WhenFull blocking behavior (as jevois::BlockingBehavior) when attempting to push into a full buffer
33  @tparam WhenEmpty blocking behavior (as jevois::BlockingBehavior) when attempting to pop from an empty buffer
34 
35  \ingroup types */
36  template <typename T, BlockingBehavior WhenFull, BlockingBehavior WhenEmpty>
38  {
39  public:
40  //! Create a new BoundedBuffer with no data and a given size
41  BoundedBuffer(size_t const siz);
42 
43  //! Push a new data element into the buffer, potentially sleeping or throwing if buffer is full, copy version
44  void push(T const & val);
45 
46  //! Push a new data element into the buffer, potentially sleeping or throwing if buffer is full, move version
47  void push(T && val);
48 
49  //! Pop oldest data element off of the buffer, potentially sleeping until one is available or throwing if empty
50  T pop();
51 
52  //! Current number of items actually in the buffer
53  /*! This function is mostly provided for informational messages and beware that the actual filled size may
54  change in a multithreaded environment between the time we return here and the time the caller tries to
55  use the result. */
56  size_t filled_size() const;
57 
58  //! Max (allocated at construction) size of the buffer
59  size_t size() const;
60 
61  //! Clear all contents, resetting filled_size() to zero (size() remains unchanged at the max possible size)
62  void clear();
63 
64  private:
65  size_t const itsSize;
66  std::queue<T> itsQueue;
67  jevois::Semaphore<WhenFull> itsEmptySemaphore;
68  jevois::Semaphore<WhenEmpty> itsFullSemaphore;
69  mutable std::mutex itsMutex;
70  };
71 } // namespace jevois
72 
73 // Include implementation details
Thread-safe synchronized producer/consumer queue.
Definition: BoundedBuffer.H:37
BoundedBuffer(size_t const siz)
Create a new BoundedBuffer with no data and a given size.
size_t filled_size() const
Current number of items actually in the buffer.
void push(T const &val)
Push a new data element into the buffer, potentially sleeping or throwing if buffer is full...
void clear()
Clear all contents, resetting filled_size() to zero (size() remains unchanged at the max possible siz...
size_t size() const
Max (allocated at construction) size of the buffer.
T pop()
Pop oldest data element off of the buffer, potentially sleeping until one is available or throwing if...