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/exceptions/software.h>
25 #include <core/threading/mutex.h>
26 #include <core/utils/refcount.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 /** Constructor. */
50 {
51  ref_mutex = new Mutex();
52  refc = 1;
53 }
54 
55 /** Destructor. */
57 {
58  delete ref_mutex;
59 }
60 
61 /** Increment reference count.
62  * @exception DestructionInProgressException Thrown if the only other reference holder
63  * for this instance was just deleting the instance when you tried to reference it.
64  * @see recount();
65  */
66 void
68 {
69  ref_mutex->lock();
70  if (refc == 0) {
71  throw DestructionInProgressException("Tried to reference that is currently being deleted");
72  }
73  ++refc;
74  ref_mutex->unlock();
75 }
76 
77 /** Decrement reference count and conditionally delete this instance.
78  * This method will decrement the reference count of this message. If the reference count
79  * reaches zero the message will be deleted automatically. So it is not safe to use this
80  * instance after is has been unref()'ed.
81  * For the code calling
82  * @code
83  * obj->unref();
84  * @endcode
85  * should be considered equivalent to
86  * @code
87  * delete obj;
88  * @endcode.
89  * There is no guarantee whatsover that the object can still be used afterwards.
90  * It is however guaranteed, that the instance is not deleted/free from memory if
91  * there are still other applications using this instance that properly ref()'ed
92  * this instance before conditional delete was called.
93  */
94 void
96 {
97  ref_mutex->lock();
98  if (refc == 0) {
99  throw DestructionInProgressException("Tried to reference that is currently being deleted");
100  }
101  if (refc > 0)
102  --refc;
103  if (refc == 0) {
104  // commit suicide
105  delete this;
106  return;
107  }
108  ref_mutex->unlock();
109 }
110 
111 /** Get reference count for this instance.
112  * The reference count is used to determine if a message should really be destructed
113  * or not.
114  * Do not rely on this value, as race-conditions may ruin your code! Do only use the
115  * atomic ref() and unref() operations. This function is only provided to output
116  * informational debugging output!
117  * @return reference count
118  */
119 unsigned int
121 {
122  return refc;
123 }
124 
125 } // end namespace fawkes
fawkes::Mutex::lock
void lock()
Lock this mutex.
Definition: mutex.cpp:91
fawkes::RefCount::unref
void unref()
Decrement reference count and conditionally delete this instance.
Definition: refcount.cpp:99
fawkes::DestructionInProgressException
Definition: software.h:59
fawkes::Mutex::unlock
void unlock()
Unlock the mutex.
Definition: mutex.cpp:135
fawkes::RefCount::ref
void ref()
Increment reference count.
Definition: refcount.cpp:71
fawkes
fawkes::RefCount::refcount
unsigned int refcount()
Get reference count for this instance.
Definition: refcount.cpp:124
fawkes::RefCount::~RefCount
virtual ~RefCount()
Destructor.
Definition: refcount.cpp:60
fawkes::RefCount::RefCount
RefCount()
Constructor.
Definition: refcount.cpp:53