Fawkes API  Fawkes Development Version
refcount.cpp
1 
2 /***************************************************************************
3  * refcount.cpp - reference counting base class
4  *
5  * Created: Fri Oct 27 13:52:08 2006
6  * Copyright 2006 Tim Niemueller [www.niemueller.de]
7  *
8  ****************************************************************************/
9 
10 /* This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version. A runtime exception applies to
14  * this software (see LICENSE.GPL_WRE file mentioned below for details).
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Library General Public License for more details.
20  *
21  * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
22  */
23 
24 #include <core/utils/refcount.h>
25 #include <core/threading/mutex.h>
26 #include <core/exceptions/software.h>
27 
28 #include <unistd.h>
29 
30 namespace fawkes {
31 
32 /** @class RefCount core/utils/refcount.h
33  * Reference counting base class.
34  * Derive this class with your object if you need reference counting for the object
35  * thus that it is not deleted while some code is still using an class instance.
36  *
37  * The RefCount class is NOT meant for direct usage. In most cases if you are aware
38  * of the need of reference couting during the design of the software derive this
39  * class. This is the recommended way. If you want to use reference counting with
40  * a class that you cannot or do not want to modify you can use the RefCounter
41  * template class to accomplish the desired task.
42  * @see RefCounter
43  *
44  * @ingroup FCL
45  * @author Tim Niemueller
46  */
47 
48 
49 /** Constructor. */
51 {
52  ref_mutex = new Mutex();
53  refc = 1;
54 }
55 
56 
57 /** Destructor. */
59 {
60  delete ref_mutex;
61 }
62 
63 
64 /** Increment reference count.
65  * @exception DestructionInProgressException Thrown if the only other reference holder
66  * for this instance was just deleting the instance when you tried to reference it.
67  * @see recount();
68  */
69 void
71 {
72  ref_mutex->lock();
73  if ( refc == 0 ) {
74  throw DestructionInProgressException("Tried to reference that is currently being deleted");
75  }
76  ++refc;
77  ref_mutex->unlock();
78 }
79 
80 
81 /** Decrement reference count and conditionally delete this instance.
82  * This method will decrement the reference count of this message. If the reference count
83  * reaches zero the message will be deleted automatically. So it is not safe to use this
84  * instance after is has been unref()'ed.
85  * For the code calling
86  * @code
87  * obj->unref();
88  * @endcode
89  * should be considered equivalent to
90  * @code
91  * delete obj;
92  * @endcode.
93  * There is no guarantee whatsover that the object can still be used afterwards.
94  * It is however guaranteed, that the instance is not deleted/free from memory if
95  * there are still other applications using this instance that properly ref()'ed
96  * this instance before conditional delete was called.
97  */
98 void
100 {
101 
102  ref_mutex->lock();
103  if ( refc == 0 ) {
104  throw DestructionInProgressException("Tried to reference that is currently being deleted");
105  }
106  if ( refc > 0 ) --refc;
107  if ( refc == 0 ) {
108  // commit suicide
109  delete this;
110  return;
111  }
112  ref_mutex->unlock();
113 }
114 
115 
116 /** Get reference count for this instance.
117  * The reference count is used to determine if a message should really be destructed
118  * or not.
119  * Do not rely on this value, as race-conditions may ruin your code! Do only use the
120  * atomic ref() and unref() operations. This function is only provided to output
121  * informational debugging output!
122  * @return reference count
123  */
124 unsigned int
126 {
127  return refc;
128 }
129 
130 
131 } // end namespace fawkes
void unref()
Decrement reference count and conditionally delete this instance.
Definition: refcount.cpp:99
unsigned int refcount()
Get reference count for this instance.
Definition: refcount.cpp:125
Fawkes library namespace.
void unlock()
Unlock the mutex.
Definition: mutex.cpp:135
void ref()
Increment reference count.
Definition: refcount.cpp:70
RefCount()
Constructor.
Definition: refcount.cpp:50
virtual ~RefCount()
Destructor.
Definition: refcount.cpp:58
void lock()
Lock this mutex.
Definition: mutex.cpp:89
Mutex mutual exclusion lock.
Definition: mutex.h:32