iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
KeyTable.H
Go to the documentation of this file.
1 /*! @file
2  @author Randolph Voorhies
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_KEYTABLE_H
37 #define INCLUDE_NRT_CORE_DESIGN_KEYTABLE_H
38 
39 #include <unordered_map>
40 #include <queue>
41 #include <stddef.h> // for size_t
42 
43 namespace nrt
44 {
45  //! A table used to create using Ids
46  /*! The KeyTable class provides a way to create unique keys, with recycling when keys get deleted. The keys are unique
47  to each instance of the class, not globally unique.
48 
49  KeyTable keeps track of the number of "users" for each Id. Each time create() is called, a user count is
50  incremented, and each time remove() is called it is decremented. If the count becomes zero during a remove(), the
51  Id is destroyed.
52 
53  \note Care must be taken when using this structure in a multithreaded environment. If not locked properly, the
54  internal structures could get messed up.
55 
56  \ingroup design */
57  template <class KeyType = size_t>
58  class KeyTable
59  {
60  public:
61  KeyTable();
62 
63  //! Create a new unique key
64  KeyType create();
65 
66  //! Get the user count for a given key, or zero if it does not exist
67  size_t users(KeyType const & key) const;
68 
69  //! Decrement the user count and, if zero, delete the key
70  /*! \return the new number of users after the decrement.
71  \throw KeyNotFoundException Thrown if value does not exist in the table. */
72  size_t remove(KeyType const & key);
73 
74  //! Clear the entire KeyTable
75  void clear();
76 
77  //! An exception type which is thrown when users try to remove an unknown key
78  class KeyNotFoundException;
79 
80  private:
81  std::map<KeyType, size_t /* numusers */> itsUsers;
82  std::queue<KeyType> itsRecycleBin;
83  KeyType itsMaxKey;
84  };
85 } // nrt
86 
88 
89 #endif // INCLUDE_NRT_CORE_DESIGN_KEYTABLE_H