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
30namespace 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 */
66void
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 */
94void
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 */
119unsigned int
121{
122 return refc;
123}
124
125} // end namespace fawkes
Mutex mutual exclusion lock.
Definition: mutex.h:33
void lock()
Lock this mutex.
Definition: mutex.cpp:87
void unlock()
Unlock the mutex.
Definition: mutex.cpp:131
void unref()
Decrement reference count and conditionally delete this instance.
Definition: refcount.cpp:95
RefCount()
Constructor.
Definition: refcount.cpp:49
void ref()
Increment reference count.
Definition: refcount.cpp:67
unsigned int refcount()
Get reference count for this instance.
Definition: refcount.cpp:120
virtual ~RefCount()
Destructor.
Definition: refcount.cpp:56
Fawkes library namespace.