Public Member Functions | Protected Types

nsAutoRef< T > Class Template Reference

template <class t>=""> class nsAutoRef More...

#include <nsAutoRef.h>

Inheritance diagram for nsAutoRef< T >:
Collaboration diagram for nsAutoRef< T >:

List of all members.

Public Member Functions

 nsAutoRef ()
 nsAutoRef (RawRefOnly aRefToRelease)
 nsAutoRef (const nsReturningRef< T > &aReturning)
ThisClassoperator= (const nsReturningRef< T > &aReturning)
 operator typename SimpleRef::RawRef () const
void steal (ThisClass &aOtherRef)
void own (RawRefOnly aRefToRelease)
void swap (ThisClass &aOther)
void reset ()
nsReturnRef< T > out ()

Protected Types

typedef nsAutoRef< T > ThisClass
typedef nsAutoRefBase< T > BaseClass
typedef nsSimpleRef< T > SimpleRef
typedef BaseClass::RawRefOnly RawRefOnly
typedef BaseClass::LocalSimpleRef LocalSimpleRef

Detailed Description

template<class T>
class nsAutoRef< T >

template <class t>=""> class nsAutoRef

A class that holds a handle to a resource that must be released. No reference is added on construction.

No copy constructor nor copy assignment operators are available, so the resource will be held until released on destruction or explicitly |reset()| or transferred through provided methods.

The publicly available methods are the public methods on this class and its public base classes |nsAutoRefBase<T>| and |nsSimpleRef<T>|.

For ref-counted resources see also |nsCountedRef<T>|. For function return values see |nsReturnRef<T>|.

For each class |T|, |nsAutoRefTraits<T>| or |nsSimpleRef<T>| must be specialized to use |nsAutoRef<T>| and |nsCountedRef<T>|.

Parameters:
T A class identifying the type of reference held by the |nsAutoRef<T>| and the unique set methods for managing references to the resource (defined by |nsAutoRefTraits<T>| or |nsSimpleRef<T>|).

Often this is the class representing the resource. Sometimes a new possibly-incomplete class may need to be declared.

Example: An Automatically closing file descriptor

// References that are simple integral types (as file-descriptors are) // usually need a new class to represent the resource and how to handle its // references. class nsRawFD;

// Specializing nsAutoRefTraits<nsRawFD> describes how to manage file // descriptors, so that nsAutoRef<nsRawFD> provides automatic closing of // its file descriptor on destruction. NS_SPECIALIZE_TEMPLATE class nsAutoRefTraits<nsRawFD> { public: // The file descriptor is held in an int. typedef int RawRef; // -1 means that there is no file associated with the handle. static int Void() { return -1; } // The file associated with a file descriptor is released with close(). static void Release(RawRef aFD) { close(aFD); } };

// A function returning a file descriptor that must be closed. nsReturnRef<nsRawFD> get_file(const char *filename) { // Constructing from a raw file descriptor assumes ownership. nsAutoRef<nsRawFD> fd(open(filename, O_RDONLY)); fcntl(fd, F_SETFD, FD_CLOEXEC); return fd.out(); }

void f() { unsigned char buf[1024];

// Hold a file descriptor for /etc/hosts in fd1. nsAutoRef<nsRawFD> fd1(get_file("/etc/hosts"));

nsAutoRef<nsRawFD> fd2; fd2.steal(fd1); // fd2 takes the file descriptor from fd1 ssize_t count = read(fd1, buf, 1024); // error fd1 has no file count = read(fd2, buf, 1024); // reads from /etc/hosts

// If the file descriptor is not stored then it is closed. get_file("/etc/login.defs"); // login.defs is closed

// Now use fd1 to hold a file descriptor for /etc/passwd. fd1 = get_file("/etc/passwd");

// The nsAutoRef<nsRawFD> can give up the file descriptor if explicitly // instructed, but the caller must then ensure that the file is closed. int rawfd = fd1.disown();

// Assume ownership of another file descriptor. fd1.own(open("/proc/1/maps");

// On destruction, fd1 closes /proc/1/maps and fd2 closes /etc/hosts, // but /etc/passwd is not closed. }


Member Typedef Documentation

template<class T >
typedef nsAutoRefBase<T> nsAutoRef< T >::BaseClass [protected]

Reimplemented in nsCountedRef< T >.

template<class T >
typedef BaseClass::LocalSimpleRef nsAutoRef< T >::LocalSimpleRef [protected]
template<class T >
typedef BaseClass::RawRefOnly nsAutoRef< T >::RawRefOnly [protected]
template<class T >
typedef nsSimpleRef<T> nsAutoRef< T >::SimpleRef [protected]

Reimplemented from nsAutoRefBase< T >.

Reimplemented in nsCountedRef< T >.

template<class T >
typedef nsAutoRef<T> nsAutoRef< T >::ThisClass [protected]

Reimplemented from nsAutoRefBase< T >.

Reimplemented in nsCountedRef< T >.


Constructor & Destructor Documentation

template<class T >
nsAutoRef< T >::nsAutoRef (  )  [inline]
template<class T >
nsAutoRef< T >::nsAutoRef ( RawRefOnly  aRefToRelease  )  [inline, explicit]
template<class T >
nsAutoRef< T >::nsAutoRef ( const nsReturningRef< T > &  aReturning  )  [inline, explicit]

Member Function Documentation

template<class T >
nsAutoRef< T >::operator typename SimpleRef::RawRef (  )  const [inline]
template<class T >
ThisClass& nsAutoRef< T >::operator= ( const nsReturningRef< T > &  aReturning  )  [inline]

Reimplemented in nsCountedRef< T >.

template<class T >
nsReturnRef<T> nsAutoRef< T >::out (  )  [inline]
template<class T >
void nsAutoRef< T >::own ( RawRefOnly  aRefToRelease  )  [inline]

Reimplemented from nsAutoRefBase< T >.

template<class T >
void nsAutoRef< T >::reset (  )  [inline]
template<class T >
void nsAutoRef< T >::steal ( ThisClass aOtherRef  )  [inline]
template<class T >
void nsAutoRef< T >::swap ( ThisClass aOther  )  [inline]

The documentation for this class was generated from the following file: