1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
/** @file
* IPRT - C++ Resource Management.
*/
/*
* Copyright (C) 2008-2025 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#ifndef IPRT_INCLUDED_cpp_autores_h
#define IPRT_INCLUDED_cpp_autores_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/types.h>
#include <iprt/assert.h>
#include <iprt/cpp/utils.h>
/** @defgroup grp_rt_cpp_autores C++ Resource Management
* @ingroup grp_rt_cpp
* @{
*/
/**
* A callable class template which returns the correct value against which an
* IPRT type must be compared to see if it is invalid.
*
* @warning This template *must* be specialised for the types it is to work with.
*/
template <class T>
inline T RTAutoResNil(void)
{
AssertFatalMsgFailed(("Unspecialized template!\n"));
return (T)0;
}
/** Specialisation of RTAutoResNil for RTFILE */
template <>
inline RTFILE RTAutoResNil(void)
{
return NIL_RTFILE;
}
/**
* A function template which calls the correct destructor for an IPRT type.
*
* @warning This template *must* be specialised for the types it is to work with.
*/
template <class T>
inline void RTAutoResDestruct(T a_h)
{
AssertFatalMsgFailed(("Unspecialized template!\n"));
NOREF(a_h);
}
/**
* An auto pointer-type class for resources which take a C-style destructor
* (RTMemFree() or equivalent).
*
* The idea of this class is to manage resources which the current code is
* responsible for freeing. By wrapping the resource in an RTCAutoRes, you
* ensure that the resource will be freed when you leave the scope in which
* the RTCAutoRes is defined, unless you explicitly release the resource.
*
* A typical use case is when a function is allocating a number of resources.
* If any single allocation fails then all other resources must be freed. If
* all allocations succeed, then the resources should be returned to the
* caller. By placing all allocated resources in RTCAutoRes containers, you
* ensure that they will be freed on failure, and only have to take care of
* releasing them when you return them.
*
* @param T The type of the resource.
* @param Destruct The function to be used to free the resource.
* This parameter must be supplied if there is no
* specialisation of RTAutoDestruct available for @a T.
* @param NilRes The function returning the NIL value for T. Required.
* This parameter must be supplied if there is no
* specialisation of RTAutoResNil available for @a T.
*
* @note The class can not be initialised directly using assignment, due
* to the lack of a copy constructor. This is intentional.
*/
template <class T, void Destruct(T) = RTAutoResDestruct<T>, T NilRes(void) = RTAutoResNil<T> >
class RTCAutoRes
: public RTCNonCopyable
{
protected:
/** The resource handle. */
T m_hRes;
public:
/**
* Constructor
*
* @param a_hRes The handle to resource to manage. Defaults to NIL.
*/
RTCAutoRes(T a_hRes = NilRes())
: m_hRes(a_hRes)
{
}
/**
* Destructor.
*
* This destroys any resource currently managed by the object.
*/
~RTCAutoRes()
{
if (m_hRes != NilRes())
Destruct(m_hRes);
}
/**
* Assignment from a value.
*
* This destroys any resource currently managed by the object
* before taking on the new one.
*
* @param a_hRes The handle to the new resource.
*/
RTCAutoRes &operator=(T a_hRes)
{
if (m_hRes != NilRes())
Destruct(m_hRes);
m_hRes = a_hRes;
return *this;
}
/**
* Checks if the resource handle is NIL or not.
*/
bool operator!()
{
return m_hRes == NilRes();
}
/**
* Give up ownership the current resource, handing it to the caller.
*
* @returns The current resource handle.
*
* @note Nothing happens to the resource when the object goes out of scope.
*/
T release(void)
{
T Tmp = m_hRes;
m_hRes = NilRes();
return Tmp;
}
/**
* Deletes the current resources.
*
* @param a_hRes Handle to a new resource to manage. Defaults to NIL.
*/
void reset(T a_hRes = NilRes())
{
if (a_hRes != m_hRes)
{
if (m_hRes != NilRes())
Destruct(m_hRes);
m_hRes = a_hRes;
}
}
/**
* Get the raw resource handle.
*
* Typically used passing the handle to some IPRT function while
* the object remains in scope.
*
* @returns The raw resource handle.
*/
T get(void)
{
return m_hRes;
}
};
/** @} */
/* include after template definition */
#include <iprt/mem.h>
#endif /* !IPRT_INCLUDED_cpp_autores_h */
|
