Introduction

Preface

This article consists of two parts. The first part describes the concept of RAII in general. The second part continues with a special application of RAII for managing dynamic objects.

What is RAII?

The worst name invented in the history of C++: RAII means 'resource acquisition is initialization'. Stroustrup: "The basic idea is to represent a resource by a local object, so that the local object's destructor will release the resource. That way, the programmer cannot forget to release the resource". A resource is "any entity that a program acquires and releases. Typical examples are free store, file handles, threads, sockets".

A misnomer: The important characteristic of RAII is that resources are released in the destructor. Resources may have been acquired in the constructor or in a member function. Weaker varieties of RAII like std::auto_ptr don't even acquire a resource.

Nevertheless RAII is a very important and valuable idiom for managing resources in C++. Moreover, RAII is a genuine C++ technique not found in other programming languages. Binding resources to a scope significantly reduces the complexity of the whole program.

Advantages of RAII

Automatic resource handling. Release (cleanup, deallocation, undo, rollback, ...) of various resources without manual interference by the user (user also needs no try, catch, finally, or using blocks).

Exception safety. Automatic resource management works for normal and exceptional program flow.

Encapsulation and information hiding. Resource acquisition and release are encapsulated in an object.

Locality of resources.

Deterministic Resource Management. You (can) know in advance when (where) the RAII objects go out of scope and therefore when the resources are released. Resources can be bound to a scope, function scope or block scope (if, do, while, for), in rare cases (Singleton) the global scope.

Challenge

Examples of RAII

void myFun()
{
XyzLib::Mutex mutex;
mutex.lock()
// do things in series ...
}
// mutex.unlock() is automatically called in the destructor of mutex

Set and reset the state of objects (devices), e.g., SetCurrentDirectory in constructor and reset it in destructor, start and stop a timer, set and reset a cursor (wait - arrow), ...

Example:

void myFun()
{
CWaitCursor waitCursor;
performLongOperation();
// ...
}
// MSDN: "The object's constructor automatically causes the wait cursor to be
// displayed. When the object goes out of scope (at the end of the block in
// which the CWaitCursor object is declared), its destructor sets the cursor
// to the previous cursor. In other words, the object performs the necessary
// clean-up automatically."

Perform undo or rollback.

Example:

void myFun (Database& db)
{
Transaction transaction (db);
transaction.beginWork();
//...
if (something.isWrong())
{
throw runtime_error ("something wrong in myFun()");
}
//...
transaction.commitWork();
}
// transaction.rollbackWork() is called in the destructor of
// transaction if transaction.commitWork() fails or is not
// reached, e.g. due to an exception

Similar tasks can be quite daunting in languages that lack destructors and thus RAII.

Managing Dynamic Objects with RAII

RAII Containers for Dynamic Objects

Stroustrup explains RAII to a former C++ programmer who pretends to never have heard about RAII during 6 years of programming in C++:

"For example, a container is a systematic way of dealing with objects. Some of the things you can have in a container are pointers to other objects, but the container's constructors and destructor can take care of contained objects. The name of the game here is to get allocation out of the way so you don't see it. If you don't directly allocate something, you don't directly deallocate it, because whoever owns it deals with it. The notion of ownership is central. A container may own its objects because they are stored directly. A container of pointers either owns the pointed-to objects or it doesn't. If it contains 1000 pointers, there's only one decision to make. Does it own them, or doesn't it? That's a 1000 to 1 reduction in complexity. As you apply this technique recursively and in as many places as you can, allocation and deallocation disappear from the surface level of your code."

Implementing a RAII Factory for Dynamic Objects

Based on the above quotation from Stroustrup, the following code implements a RAII factory for dynamic objects. I use the term 'factory' here and not 'container' to avoid confusion with traditional containers, e.g., STL containers, and to emphasize the 'creational aspect'. Clarification: Neither the name 'RAII Factory' nor the following code stem from Bjarne Stroustrup.

Nothing fancy. MyClassFactory consists of a few lines of boilerplate code that forwards arguments to the MyClass constructor, calls the imp.keep() function, and returns the created object to the caller.

Common RAII factory code is factored out into an implementation class template called RaiiFactoryImp. Concrete RAII factories like MyClassFactory delegate repetitive functions to it.

Using the code: Place the RAII factory in the right scope and create as much dynamic objects as you need. All created objects are destroyed at the end of the scope, i.e., when the RAII factory goes out of scope.

Features of RAII Factory

A RAII factory creates and stores objects. The create() function forwards arguments to the object's constructor.

Objects are either fully created and returned to the caller or an exception is thrown. There is no need to check the returned pointer for NULLness.

When the factory goes out of scope, it deletes all created objects in the destructor. The factory is non-copyable. The lifetime of objects is bound to a scope ('scope based resource management'). Programming with scope instead of programming with new and delete.

new and delete are encapsulated.

A factory owns created objects for their entire lifetime. There is no transfer of ownership, no release or detach function. The factory only lends objects to the user. This is also known as 'Producer-Product pattern' or 'Creator as Sole Owner pattern'.

Ease of use: The RAII factory implementation above contains no template parameters in the user interface.

Non-intrusive: RAII factories for third party classes can be written without changing the third party classes.

What is the Right Scope for a RAII Factory?

The RAII Factory deletes all objects when it goes out of scope. You have to put the factory in the right scope. But what is the right scope?

In general, the right scope is the scope in which the created objects are used. The lifetime of created objects cannot exceed the lifetime of the owning RAII factory. Returning a created object from the scope of the factory would crash the program. Of course, created objects and the factory can be passed 'down' to other functions by reference or by address.

The "Minimal Scoping Rule": Objects should not loiter around. They should only exist for the time, better, the scope they are needed: the minimal, lowest possible scope.

The lifetime of the RAII factory should exceed the lifetime of all pointers to created objects in order to avoid dangling pointers. The RAII factory should not go out of scope when pointers to created objects still exit.

When to use a RAII factory?

If you know in advance that you want to create only one object, you don't need to dynamically allocate anything and you also don't need a RAII factory. Just put the object on the stack. Likewise, for a fixed number of objects, you will probably use a stack-based array.

For an unknown number of objects - unknown at compile time - we have to distinguish between value objects and entity objects. See this article for a brief description of the distinction between value objects (Point, Date, ...) and entity objects (Account, DataBaseConnection, ...).

To create an unknown number of value objects, you typically copy each created object by value into a container and work with the container further on (iterate, search, sort, ...). Copying value objects is semantically correct and usually computationally cheap. There is no need for a RAII-Factory in this case, e.g.:

A RAII factory is the right tool to create an unknown number of entity objects. Usually entity objects are non-copyable. In a sense, a RAII factory is a mechanism to 'extend' the stack for an indeterminate number of entity objects.

Extending RAII-Factory

The RAII factory described so far contains the basic implementation that can be extended in various ways. Examples:

An OO Variant

The following example outlines an OO variant of a RAII factory that produces base and derived class objects alike (if the constructor parameters match).

Note how the create function is defined and invoked as factory.create<MyBase>() or factory.create<MyDerived>(). The type of the object actually created is specified in angle brackets after the function name. This is called 'explicit function template argument specification'. You need a C++ compiler with advanced template support for this to work (not with VC++ 6.0).

A Generic RAII Factory

GFactory<T> is a class template that can be used to create objects of (almost) any type T. One limitation of this approach stems from the fact that many overloaded create() function templates are needed in GFactory because create() should support all combinations of const and non-const template parameters. Currently, GFactory<T>.create() can take up to 8 arguments (up to 16 if all arguments are const). The VC++ 6.0 compiler sometimes reports ambiguous calls (workaround: cast arguments to their type, see source code download for details). Current compilers like the VC++ 7.1 and the GCC 3.4 compiler work as expected.

Disposing Objects

Sometimes (rarely) you need to immediately destroy an object instead of waiting until the RAII factory goes out of scope. For this purpose, a dispose() function can be implemented. Be sure though that no dangling pointer is left in your code in this case.

Factory, Container, or Both?

Is a RAII factory just another container with additional create() functions to accomplish continuous ownership of created objects?

Which container functions should be added to a RAII factory then?

Should there even be a raii_factory_vector, raii_factory_list, raii_factory_map, etc.?

There are some good reasons to separate creation (factory) from iteration and other container functionality. This way you create objects by using a RAII factory and put them in a different, specialized container - preferably in a container appropriate for pointers like ptr_vector or in a hash table for fast access by key. Separation of concerns provides for flexibility in this case.

On the other hand, an all-in-one solution also has its merits. It's convenient to create and use objects in one place. In an example in the source code download, operator[] is implemented which can be used as iterator through the RAII factory, e.g.:

So, what's the main difference between usual containers and RAII factories? Whereas containers are generic data structures, RAII factories are much more specialized in their objective. Resource management is only their most basic purpose. You easily come up with many useful features that you want to add to a RAII factory.

A powerful application of RAII factories are tree-like structures where each parent element produces n child elements which in turn become parent elements and so on. Many real world domains can naturally and efficiently be modeled as hierarchies of objects that produce and own their descendants.

Alternatives to RAII Factories

Manual Management of Dynamic Objects

Maybe you have seen C++ programs with new and delete statements scattered around the code, sometimes decorated with many try/catch blocks. This is a maintenance nightmare ("Shall I delete this object here or is it used further on?") and a resource management 'anti-pattern'. Most horror stories about 'memory problems' in C++ programs stem from people who have tried this approach. Manual management of dynamic objects, resources in general, is impractical for any but very small applications.

'Smart Pointers'

'Smart pointers' are not pointers but objects that mimic one aspect of pointers, that is, dereferencing. Additionally, they perform some extra, 'smart' task. E.g., std::auto_ptr and reference-counted 'smart pointers' manage the lifetime of objects for which a pointer is passed to them. In many cases, this combination of (partial) pointer functionality and resource management produces more troubles than benefits. Furthermore, resource-managing 'smart pointers' thwart deterministic resource management (you can always return, e.g., an auto_ptr). If you ask me, I would avoid 'smart pointers'. However, 'smart pointer' certainly is the best name invented in the history of C++.

Garbage Collection

Garbage Collection (GC) is a runtime mechanism that recycles unreferenced memory ('garbage') but offers no guarantee for the controlled destruction of objects. GC defeats the purpose of RAII and the unique advantage of C++: deterministic encapsulated resource management. You neither know when the collector kicks in nor when and if a 'finalizer' is called (and are even advised to avoid using a Finalize method). Exception handling gets complicated in GC languages because the responsibility of releasing resources other than pure memory is shifted on to the user. Strangely enough, GC does not necessarily prevent memory leaks [link1, link2, link3]. For C++, there is hardly a good reason to trade RAII for GC.

Conclusion

After a recap of the basic idea of RAII, this article has presented RAII factories, a special variety of RAII to handle dynamic objects. Compared to C++ code that is unaware of it, RAII saves you most new and delete statements. Compared to GC languages, RAII saves you most try, catch, finally, and using blocks. RAII fosters a C++ programming style that greatly simplifies resource handling. In Stroustrup's words again: "As you apply this technique recursively and in as many places as you can, allocation and deallocation disappear from the surface level of your code".

History

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

Comments and Discussions

None, because I don't use them. (in general, the same as for auto_ptr plus the unnecessary dynamically allocated counter object in each r.c.s.p.)

Well, I think there's too much religion and very few science in this kind of answers:

I don't pretend to offend anyone, but is a matter of fact that –even if all catholic Popes still disagree about the use of condoms and of sex outside marriage- the most of self-saying "catholic people" use them and have sex before marriage.

The metaphor is to say only one concept: whatever "right" can be a thing you would like to be, that "thing" will always go its own way, with a "best compromise" logic, when applied on a wide population. You can "influence it", not change it in its nature.
But programming should be a science, not a religion.

Smart pointers everywhere is wrong as RAII everywhere is wrong.
The good programmer choose the –case by case- the pattern that best fits please notethe program needs (not his own needs). Object lifetime is not always something you can decide aprioristically. And "determinism" is not the concept you mention (well … not in the official mathematical sense). Destruction by reference counting is deterministic as destruction in scope. (Smart pointers are destroyed by scope, after all…) GC isn't because the destruction action is not taken as direct consequence of a program action.

To say "I don't have problem because I don't use it" describing another pattern as a replacement for that, doesn't make a good impression. There's nothing scientifically meaningful in that.

I use reference counting widely without any particular problem. As I use RAII. I'm diffident of GC in C++ program, not because I'm diffident on GC, but because I don't see (unlike for RAII and smart pointer) any binding with any C++ native scoping mechanism.

None, because I don't use them. (in general, the same as for auto_ptr plus the unnecessary dynamically allocated counter object in each r.c.s.p.)

Well, I think there's too much religion and very few science in this kind of answers ..
Smart pointers everywhere is wrong as RAII everywhere is wrong.

As I said before, RAII can hardly be overused (at least I don't see how).

The good programmer choose the –case by case- the pattern that best fits please note the program needs (not his own needs). Object lifetime is not always something you can decide aprioristically.

You start case by case and gradually develop towards styles, idioms, patterns. A library, e.g., must conform to a certain 'philosophy' to be usable. The little sister of KISS is KIU (Keep It Uniform ).

And "determinism" is not the concept you mention (well … not in the official mathematical sense). Destruction by reference counting is deterministic as destruction in scope. (Smart pointers are destroyed by scope, after all…)

If you return a smart pointer to a resource that may be returned again then you can hardly call this 'deterministic'. The usage of 'deterministic' here is close to the ACID properties of database transactions (see also link to Herb Sutters article above).

To say "I don't have problem because I don't use it" describing another pattern as a replacement for that, doesn't make a good impression. There's nothing scientifically meaningful in that.

I don't use resource-owning smart pointers because they mix two unrelated concepts: (de-)referencing and resource-handling. Besides that, 'smart pointers' are not pointers, i.e. they cannot provide the full syntax of pointers.

I use reference counting widely without any particular problem.

IMO, reference-counting works well when it's an implementation detail, invisible to the user (when r.c. is encapsulted).

You're still climbing glasses, my friend!
Many acronym and citation... and no samples by you!
Let me do a counter example: consider an application that lets a user editing a document by placing, moving and removing a variety of objects (in human-language common sense). Think to MS PowerPoint, for example.

The fact that the user has a "delete" command in a menu, doesn’t make you able to "destroy by scope". The scope in which the objects live is the document. If you destroy the document you destroy the objects. Right: RAII factory works.
But what about a "delete" command? You can remove the objects –oops! The object pointers- from the objects collection that represent the document [1], but the objects will be still there until the document will be closed.
Now, think a user inserting 10 thousand object, "deleting" them, inserting other 10 thousand ... three four five ... one hundred times. When do you'll ever eliminate the "deleted" 100thousand objects?
Are you going to fill-up the entire memory with things the users will no more access anyway?

Now, consider a reference counting pointer with casting capability inside a collection, and all object sharing a same common base. The user choose "delete", and you remove the "pointer" from the collection representing the document. Full stop. The object will continue to exist only if it is also referred from inside another collection (for example an "undo" list) and will be deleted when no more needed[2].

You can think this is ugly, you can find as many people you want that agree. Burt you cannot say this doesn't work, or that it "has problems"! That fact that many people agree on something doesn't make that something "true". Fore a science things are "true" when replicate coherently, independently on "opinions". "Good" and "Bad" .. it is another story.

If this "have problems" tell me "what are the problems". I don't see any. May be I'm wrong, but you did nothing to explain me. You simple say "I feel this's wrong".

But saying "I don't use so I don't have problem ..." is like saying by definitiomn "true = good / false = bad". That's not a definition. It's a prejudice.

[1] Please note that such a collection must have a polymorphic content: hence forget about the STL "value semantic": pointers and virtual function, in these cases, are a must. Inheritace of template parameter (that is: policy design of the objects) doesn't help a lot.

[2] This is still "determinism" since "when no more needed" is a well defined and predictable event. The fact that someone use this name in more strict definition, doesn't change the nature of things. "Deterministic" is a legitimate Englis dictionary term. And the fact that someone use acronyms to give a "hidden name" to this misinterpretation of words, doesn't change the physics, nor the language. It is not "when someone will be interested in looking if no more needed", like in GC. That's non-determinism.
Again: you can think this is "hugly", but you cannot say "it's wrong".

emilio_grv wrote:You're still climbing glasses, my friend!
Many acronym and citation... and no samples by you!
Let me do a counter example: consider an application that lets a user editing a document by placing, moving and removing a variety of objects ... Are you going to fill-up the entire memory with things the users will no more access anyway?

Maybe my emamples are somewhat misleading (I consider updating them). The article states the "Minimal Scoping Rule" and has a chapter 'Disposing Objects'.

Now, consider a reference counting pointer with casting capability inside a collection, and all object sharing a same common base. The user choose "delete", and you remove the "pointer" from the collection representing the document. Full stop. The object will continue to exist only if it is also referred from inside another collection (for example an "undo" list) and will be deleted when no more needed[2].

Your document example is very interesting. I'd say that the document is a RAII-factory that owns all created objects. Two 'views' work on that document: one consists of the visible objects and the other of the objects that are currently invisible but still part of the document. Objects without further usability are disposed.
The article already is too long. I've considerd to include a longer, more realistic, example, e.g. an XML document where elements are viewed as (a hierarchy of) RAIIFactories that create and own child-elements and attributes.

You can think this is ugly, you can find as many people you want that agree. Burt you cannot say this doesn't work, or that it "has problems"! That fact that many people agree on something doesn't make that something "true". Fore a science things are "true" when replicate coherently, independently on "opinions". "Good" and "Bad" .. it is another story.

Well, this is not an article about the (dis-)advantages of 'smart pointers'. I almost regret to have mentioned them in the article since they seem to distract people from the actual contents.

[1] Please note that such a collection must have a polymorphic content: hence forget about the STL "value semantic": pointers and virtual function, in these cases, are a must. Inheritace of template parameter (that is: policy design of the objects) doesn't help a lot.

You may want to have a look at my other CP article: ptr_vector[^] which could be used/combined/merged with a RAIIFactory.

[2] This is still "determinism" since "when no more needed" is a well defined and predictable event. The fact that someone use this name in more strict definition, doesn't change the nature of things. "Deterministic" is a legitimate Englis dictionary term. And the fact that someone use acronyms to give a "hidden name" to this misinterpretation of words, doesn't change the physics, nor the language. It is not "when someone will be interested in looking if no more needed", like in GC. That's non-determinism. Again: you can think this is "hugly", but you cannot say "it's wrong".

I think it is unfruitful to stick to one word: If you prefer call it: 'resource management bound to one function scope or one block scope'. That's what it is.

I'd say that the document is a RAII-factory that owns all created objects. Two 'views' work on that document: one consists of the visible objects and the other of the objects that are currently invisible but still part of the document. Objects without further usability are disposed

How do you know they have no "further usability"? I don't see anything keeping track of this. The RAII factory says "You exist until I exist". The concept of "usable" is not there. You must count who's using. But this is –back again- reference counting. That doesn't mean by itself "smart pointers", but you still have to count! (see back "rm82" message ...)
Or you can "migrate" a user "deleted" object to another factory... that will destroy sooner; violating the pattern.

You may want to have a look at my other CP article: ptr_vector which could be used/combined/merged with a RAIIFactory.

Sure: it works fine. But the point is not the "pointer", but what it points: must be a (same) interface that each different object "reinterpret". You call "paint". But "paint" paints differently depending on object type. But this is something that does not relate to refocounting or RAII, but with polymorphism. That's another story.

I'd say that the document is a RAII-factory that owns all created objects. Two 'views' work on that document: one consists of the visible objects and the other of the objects that are currently invisible but still part of the document. Objects without further usability are disposed

How do you know they have no "further usability"? I don't see anything keeping track of this. The RAII factory says "You exist until I exist". The concept of "usable" is not there.

You are right, it's not there, because it is application logic. The RAIIFactory only encapsulates resource handling via RAII so that "allocation and deallocation disappear from the surface level of your code."

You must count who's using. But this is –back again- reference counting. That doesn't mean by itself "smart pointers", but you still have to count! (see back "rm82" message ...)

You probably mean a situation, where many 'subscribers' reference the same 'published' resource. In this case you probably find an easier solution with (internal or external) refernce-counting (but that makes it harder to track down the lifetime of a resource). RAII, scope bound resource management to be more precise, is not a panacea but it works very well in many cases. Not all though.

To me at least, they are totally deterministic. When the last smart pointer assigned to a pointer is deleted, the pointed-to object will be deleted. Just because it may not happen in a function or trivial scope doesn't mean it's non-deterministic.

I also think your advice to avoid returning resources from functions (and presumably acting as sinks too) is misguided. It's a common, well-known and useful C++ idiom. (See Sutter's books or even his treatise online)

The rest of your article was reasonable and you should be applauded for discouraging the use of new/delete. Although I have to say I would avoid using your RAII factories in favour of smart pointers and standard containers. IMO they are more robust, readable and, well, standard.

MattyT wrote:I have trouble with your smart pointer definitions too.
To me at least, they are totally deterministic. When the last smart pointer assigned to a pointer is deleted, the pointed-to object will be deleted. Just because it may not happen in a function or trivial scope doesn't mean it's non-deterministic.

You may call it 'resource management bound to one function scope or one block scope' instead of 'deterministic resource management'. Ref-counted smart pointers are not bound to one scope.

I also think your advice to avoid returning resources from functions (and presumably acting as sinks too) is misguided. It's a common, well-known and useful C++ idiom. (See Sutter's books or even his treatise online)

Ok, to be fair, the full quotation of the last sentence is: "Avoid using auto_ptr, instead use shared_ptr which is widely available and being added to the standard library." And to avoid misunderstanding: I recommend of course his books (I have the two 'Exceptional C++') and all his articles, Gotw, ...

It seems to me that many 'smart pointers' (like auto_ptr) are so smart that they outsmart their users.

Hi,
good article.
But is RAII really so good,
that GC is not necessary anymore?
Furthermore, is it true, that
"Exception handling gets complicated in GC languages ".
In Java and .Net Exception handling is the standard way
of error handling and both have GC.
I beleive that you are a bit overoptimistic about RAII.
Best Regards
Martin

GC is not a replacement for RAII. It can handle only memory, while leaving all other resources (db connections, files, GDI handles, sockets...) to programmer to handle manually. One solution is to have them both, like in C++/CLI, but I strongly prefer to have GC only as an option on a per-object basis. As for .NET and Java, I have seen so many programmers (heck, even book writers) write exception non-safe code, that I would argue these environments are seriously flawed in this regard. See this article by Reymond Chen[^], for instance.

Anyway, I voted this article 5, although I don't quite agree with author's criticisms for smart pointers. I use Boost smart pointers (especially scoped_ptr) all the time, and practically never call delete manually any more. As for RAII factory, I used this idiom once (although I had no idea it was called RAII factory ) when I didn't have a clear owner of my objects and wanted to avoid the overhead of reference counting. However, I exactly new the point in my program where it was safe to destruct the objects - it is not always the case.

Nemanja Trifunovic wrote:GC is not a replacement for RAII. It can handle only memory, while leaving all other resources (db connections, files, GDI handles, sockets...) to programmer to handle manually.[...] As for .NET and Java, I have seen so many programmers (heck, even book writers) write exception non-safe code, that I would argue these environments are seriously flawed in this regard. See this article by Reymond Chen[^], for instance.

That's the point. Many programmers in GC languages seem to be unaware of the problematic of releasing resources and the right resource-handling idioms (e.g. the 'Null' object).

Anyway, I voted this article 5, although I don't quite agree with author's criticisms for smart pointers. I use Boost smart pointers (especially scoped_ptr) all the time, and practically never call delete manually any more.

Yes, real C++ programmers don't call delete manually. Seriously!
I also use scoped resource handlers for just one object (but not 'smart pointers') in some cases when it's not possible to create the object on the stack.

Finally, I recommend this article[^] as a nice introduction to RAII.

Good article. I've known it. Unfortunately it does not define RAII, it assumes that you already know RAII.

Yep, real programmers don't need to dynamically allocate everything on the planet like 99% of supposed "programmers" out there. Please ignore this - just a game programmer's view of the trends of programming in general... bloat all the way!

Furthermore, is it true, that
"Exception handling gets complicated in GC languages ".
In Java and .Net Exception handling is the standard way
of error handling and both have GC.

In Java (the language I have worked with) the user has to write code over and over again that in C++ can be written in the destructor once and forever.

I believe that you are a bit overoptimistic about RAII.

Maybe. The RAII idiom is underestimated in C++. Partly because of the bad name, partly because RAII is not so "smart" as some "policy-based" designs.
RAII is not a panacea but a cure for most resource management problems. And it can hardly be overused.