Loading...
Searching...
No Matches
PtrHolder.h
Go to the documentation of this file.
//# PtrHolder.h: Hold and delete pointers not deleted by object destructors
//# Copyright (C) 1994,1995,1999,2000
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library 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 Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef CASA_PTRHOLDER_H
#define CASA_PTRHOLDER_H
//# Includes
#include <casacore/casa/aips.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// <summary>
// Hold and delete pointers not deleted by object destructors
// </summary>
// <use visibility=export>
// <reviewed reviewer="troberts" date="1995/07/29" tests="tPtrHolder">
// </reviewed>
// <prerequisite>
// <li> module <linkto module=Exceptions>Exceptions</linkto>
// </prerequisite>
// <synopsis>
// <src>PtrHolder</src>s hold allocated pointers which should be
// deleted when an exception is thrown. Exceptions only call destructors
// of objects. Thus, for example, storage allocated in a global function
// (outside of an object)is not deleted. A <src>PtrHolder</src> solves
// this problem: it merely holds the pointer and deletes it when it is
// destroyed itself, e.g. when an exception is thrown or when the
// function exits normally.
// </synopsis>
// <example>
// <srcblock>
// void func(Int *ptr); // some other function that takes a pointer
// // ...
// // True below means it's an array, False (the default) would mean
// // a singleton object.
// PtrHolder<Int> iholder(new Int[10000], True);
// func(iholder); // converts automatically to ptr
// (iholder.ptr() + 5) = 11; // use pointer explicitly
// some_function_that_throws_exception(); // pointer is deleted
// </srcblock>
// </example>
// <motivation>
// Avoid leaks when throwing/catching exceptions.
// </motivation>
// <todo asof="2000/04/11">
// <li> Use the autoptr class from the Standard Library
// </todo>
template<class T> class PtrHolder
{
public:
// The default constructor uses a null pointer.
[[deprecated("Use std::unique_ptr")]]
PtrHolder();
// Construct a <src>PtrHolder</src> from a pointer which MUST have
// been allocated from <src>new</src>, since the destructor will
// call <src>delete</src> on it. If the pointer is to an array,
// i.e. allocated with operator <src>new[]</src>, then
// <src>isCarray</src> should be set to True. (This parameter is
// required because C-arrays need to be deleted with
// <src>delete[]</src>.)
//
// After the pointer is placed into the holder, the user should
// not manually delete the pointer; the <src>PtrHolder</src>
// object will do that, unless <src>set()</src> or
// <src>clear()</src> is called with <src>deleteCurrentPtr</src>
// set to False. The pointer must also only be put into
// <em>one</em> holder to avoid double deletion.
[[deprecated("Use std::unique_ptr")]]
PtrHolder(T *pointer, Bool isCArray = False);
~PtrHolder();
// Set the pointer to a new value. If <src>deleteCurrentPtr </src>is
// True (the default), then delete the existing pointer first. If
// <src>isCarray</src> is True, then the new pointer is assumed to
// have been allocated with <src>new[]</src>.
void set(T *pointer, Bool isCarray = False, Bool deleteCurrentPtr = True);
// Set the current pointer to null; if <src>deletePtr</src> is True
// (the default), then the current pointer is deleted first.
void clear(Bool deleteCurrentPtr = True);
// Release the pointer for use.
// <group>
T *ptr() { return ptr_p; }
const T *ptr() const { return ptr_p; }
// </group>
// Attempt to automatically release a pointer when required. If the
// compiler can't figure it out, you can use the <src>ptr()</src>
// member function directly.
operator T *() { return ptr_p; }
operator T *() const { return ptr_p; }
// </group>
// Make it possible to use -> on the pointer object.
T* operator->() const
{ return ptr_p; }
// See if the pointer points to a C-array.
Bool isCArray() const {return isCarray_p;}
private:
//# Undefined and inaccessible
PtrHolder(const PtrHolder<T> &other);
PtrHolder<T> &operator=(const PtrHolder<T> &other);
//# We'd also like the following to be undefined and inaccessible,
//# unfortunately CFront doesn't seem to let you do that.
//# void *operator new(size_t s);
//# Put functionality in one place
void delete_pointer_if_necessary();
T *ptr_p;
//# If space were critical, we could make isCarray_p a char
Bool isCarray_p;
};
// <summary>
// Hold and delete pointers not deleted by object destructors
// </summary>
// <use visibility=export>
// <reviewed reviewer="" date="" tests="tPtrHolder">
// </reviewed>
// <prerequisite>
// <li> module <linkto module=Exceptions>Exceptions</linkto>
// </prerequisite>
// <synopsis>
// <src>SPtrHolder</src>s hold allocated pointers to non-array objects
// which should be deleted when an exception is thrown.
// SPtrHolder is similar to PtrHolder, but easier to use and only valid
// for pointer to a single object, thus not to a C-array of objects.
// </synopsis>
// <example>
// <srcblock>
// void func(Table *ptr); // some other function that takes a pointer
// // ...
// // True below means it's an array, False (the default) would mean
// // a singleton object.
// SPtrHolder<Int> iholder(new Table(...));
// func(iholder); // converts automatically to ptr
// Table* tab = iholder.transfer(); // transfer ownership
// </srcblock>
// If an exception is thrown in function <src>func</src>, the Table will be
// deleted automatically. After the function call, the ownership is tranfered
// back to the 'user'
// </example>
// <motivation>
// <src>std::auto_ptr</src> is harder to use and its future is unclear.
// <br>
// <src>PtrHolder</src> is not fully inlined and has C-array overhead.
// Furthermore the automatic conversion to a T* is dangerous, because the
// programmer may not be aware that the pointer is maybe taken over.
// </motivation>
template<class T> class SPtrHolder
{
public:
// Construct an <src>SPtrHolder</src> from a pointer which MUST have
// been allocated from <src>new</src>, since the destructor will
// After the pointer is placed into the holder, the user should
// not manually delete the pointer unless the transfer function is called.
// The pointer must also only be put into
// <em>one</em> holder to avoid double deletion.
explicit SPtrHolder (T* ptr = 0)
: itsPtr(ptr) {}
~SPtrHolder()
{ delete itsPtr; }
// Reset the pointer.
void reset (T* ptr)
{ if (ptr != itsPtr) { delete itsPtr; itsPtr = ptr; }}
// Transfer ownership of the pointer.
// I.e. return the pointer and set it to 0 in the object.
T* transfer()
{ T* ptr = itsPtr; itsPtr = 0; return ptr; }
// Release the pointer.
void release()
{ itsPtr = 0; }
// Make it possible to dereference the pointer object.
// <group>
T& operator*()
{ return *itsPtr; }
const T& operator*() const
{ return *itsPtr; }
// </group>
// Make it possible to use -> on the pointer object.
T* operator->() const
{ return itsPtr; }
// Get the pointer for use.
// <group>
T* ptr()
{ return itsPtr; }
const T* ptr() const
{ return itsPtr; }
// </group>
private:
// SPrtHolder cannot be copied.
// <group>
SPtrHolder(const SPtrHolder<T> &other);
SPtrHolder<T> &operator=(const SPtrHolder<T> &other);
// </group>
//# The pointer itself.
T* itsPtr;
};
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/casa/Utilities/PtrHolder.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
SPtrHolder::ptr
T * ptr()
Get the pointer for use.
Definition PtrHolder.h:238
SPtrHolder::transfer
T * transfer()
Transfer ownership of the pointer.
Definition PtrHolder.h:217
SPtrHolder::itsPtr
T * itsPtr
Definition PtrHolder.h:252
SPtrHolder::operator*
const T & operator*() const
Definition PtrHolder.h:228
SPtrHolder::~SPtrHolder
~SPtrHolder()
Definition PtrHolder.h:208
SPtrHolder::release
void release()
Release the pointer.
Definition PtrHolder.h:221
SPtrHolder::SPtrHolder
SPtrHolder(const SPtrHolder< T > &other)
SPrtHolder cannot be copied.
SPtrHolder::operator=
SPtrHolder< T > & operator=(const SPtrHolder< T > &other)
SPtrHolder::operator->
T * operator->() const
Make it possible to use -> on the pointer object.
Definition PtrHolder.h:233
SPtrHolder::reset
void reset(T *ptr)
Reset the pointer.
Definition PtrHolder.h:212
SPtrHolder::operator*
T & operator*()
Make it possible to dereference the pointer object.
Definition PtrHolder.h:226
SPtrHolder::ptr
const T * ptr() const
Definition PtrHolder.h:240
SPtrHolder::SPtrHolder
SPtrHolder(T *ptr=0)
Construct an SPtrHolder from a pointer which MUST have been allocated from new, since the destructor ...
Definition PtrHolder.h:205
casacore::PtrHolder
Definition PtrHolder.h:79
casacore::PtrHolder::~PtrHolder
~PtrHolder()
casacore::PtrHolder::PtrHolder
PtrHolder()
The default constructor uses a null pointer.
casacore::PtrHolder::PtrHolder
PtrHolder(T *pointer, Bool isCArray=False)
Construct a PtrHolder from a pointer which MUST have been allocated from new, since the destructor wi...
casacore::PtrHolder::set
void set(T *pointer, Bool isCarray=False, Bool deleteCurrentPtr=True)
Set the pointer to a new value.
casacore::PtrHolder::ptr
T * ptr()
Release the pointer for use.
Definition PtrHolder.h:116
casacore::PtrHolder::clear
void clear(Bool deleteCurrentPtr=True)
Set the current pointer to null; if deletePtr is True (the default), then the current pointer is dele...
casacore::PtrHolder::ptr
const T * ptr() const
Definition PtrHolder.h:117
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::False
const Bool False
Definition aipstype.h:42
casacore::isCarray_p
Bool isCarray_p
Definition PtrHolder.h:148
casacore::operator->
T * operator->() const
Make it possible to use -> on the pointer object.
Definition PtrHolder.h:128
casacore::delete_pointer_if_necessary
void delete_pointer_if_necessary()
casacore::isCArray
Bool isCArray() const
See if the pointer points to a C-array.
Definition PtrHolder.h:132
casacore::operator=
Record & operator=(const Record &other)
Copy the data in the other record to this record.
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::PtrHolder
PtrHolder(const PtrHolder< T > &other)
casacore::True
const Bool True
Definition aipstype.h:41
casacore::ptr_p
T * ptr_p
Definition PtrHolder.h:146