VirtualBox

source: vbox/trunk/include/iprt/cpp/autores.h@ 56291

Last change on this file since 56291 was 56291, checked in by vboxsync, 10 years ago

include: Updated (C) year.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette