iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
BoundedSet.H
Go to the documentation of this file.
1 /*! @file
2  @author Laurent Itti
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_DESIGN_BOUNDEDSET_H
37 #define INCLUDE_NRT_CORE_DESIGN_BOUNDEDSET_H
38 
40 #include <nrt/Core/Typing/Enum.H>
41 #include <deque>
42 #include <functional>
43 
44 namespace nrt
45 {
46  //! BoundedSet insert policy
47  /*! \class BoundedSetInsertPolicy
48  When trying to push a new element into the set, if it matches one already in the set:
49 
50  - if \c nrt::BoundedSetInsertPolicy::Preserve, keep the old one and discard the new incoming one, or,
51  - if \c nrt::BoundedSetInsertPolicy::Replace, replace the old one with the new one.
52 
53  \relates BoundedSet */
54  NRT_DEFINE_ENUM_CLASS(BoundedSetInsertPolicy, (Preserve) (Replace) );
55 
56  //! Thread-safe synchronized producer/consumer queue with element replacement policy
57  /*! BoundedSet is designed for use in producer/consumer scenarios where multiple threads wish to push and pop data
58  onto/from the set asynchronously. Threads that try to pop data when the set is empty will sleep until data is
59  actually available, and threads that try to push data when the set is full will block until some space is
60  available in the set. Threads that try to push an element that is already in the set will see that element pushed
61  or not according to the insert policy.
62 
63  \ingroup design */
64  template <class T, typename EqualsTo = std::equal_to<T> >
65  class BoundedSet
66  {
67  public:
68  //! Create a new BoundedSet with no data
69  BoundedSet(size_t const siz, EqualsTo const & eq = EqualsTo());
70 
71  //! Push a new data element into the set, potentially sleeping if set is full
72  void push(T const & val, BoundedSetInsertPolicy const pol = BoundedSetInsertPolicy::Preserve);
73 
74  //! Pop oldest data element off of the set, potentially sleeping until one is available
75  T pop();
76 
77  //! Current number of items actually in the set
78  size_t const filled_size();
79 
80  //! Max size of the set
81  size_t const size() const;
82 
83  private:
84  bool tryReplace(T const & val, BoundedSetInsertPolicy const pol);
85 
86  size_t const itsSize;
87  std::deque<T> itsQueue;
88  nrt::Semaphore itsEmptySemaphore, itsFullSemaphore;
89  std::mutex itsMutex;
90  EqualsTo const itsEqualsTo;
91  };
92 } // namespace nrt
93 
95 
96 #endif // INCLUDE_NRT_CORE_DESIGN_BOUNDEDSET_H
97