---

arg library

Introduction to arglib

This is a C++ library, it contains a mixture of stable, useful classes and "doodles in code". These are provided "as is" without any guarantees.

There are also tutorial articles discussing the rationale and usage of the various library elements. It is a "work in progress": enhancement and additional articles will be posted as and when I get around to it.

All the code has been compiled and tested with egcs-1.1.2, gcc 2.95.2 Visual C++ 5.0 Visual C++ 6.0 and Borland C++ 5.5 on WinNT4/Intel and with gcc 2.95.2 on Solaris7/Sparc.

Overview of contents

arglib contains the following headers (A more detailed discussion of the smart pointers is below):

"arg_shared.h"

This provides arg::counted_ptr<> which supports a form of shared ownership. This and the related arg::uncounted_ptr<> are discussed in the "uncounted pointer" article

"arg_grin_ptr.h"

This provides arg::grin_ptr<> which provides supports for the "Cheshire Cat" idiom. Copy and assignment operations replicate the owned object. (This differs from the similar arg::deep_copy_ptr<> in that - with the exception of the explicit constructor - the methods do not depend upon the pointee being of a complete type. More details in Ending with the grin.

"arg_deep_copy.h"

This provides arg::deep_copy_ptr<> which supports a form of unshared ownership. (Copy operations duplicate the owned object.) This and the related arg::body_part_ptr<> will be the subject of a future article.

"arg_auto_ptr.h"

This is just my attempt to implement the standard library auto_ptr template. It has no utility except when working with C++ implementations that supply a broken auto_ptr.

"arg_observer.h"

Support template classes for implementing the GOF observer pattern. (Principally a subject template class.)

"arg_iterator.h"

Proxy template classes for wrapping iterators. These allow the a class interface to be defined without exposing the choice of used in the implementation.

"arg_deep_copy_utils.h"

Provides a template function deep_copy() to to copy the object referenced by a pointer. (Using a copy constructor, a clone() method and using a makeClone() method are all supported - users may also supply alternatives.) The pointer template classes in "arg_deep_copy.h" and "arg_grin_ptr.h" use this to copy the objects they manage correctly.

"arg_test.h"

This provides a number of utilities used by the test harnesses. At present there is no tutorial, but plenty of examples.

Smart pointers

The headers "arg_shared.h", "arg_grin_ptr.h", "arg_deep_copy.h" and "arg_auto_ptr.h" all provide smart pointers that manage an "owned" object. This may seem a little confusing at first - but they do meet different needs. The following table and glossary attempt to resolve any confusion.

Pointer	Ownership	Copying	Incomplete Types	Const-qualified
arg::counted_ptr	shared	value	no	no
arg::uncounted_ptr	no	value	no	no
arg::deep_copy_ptr	sole	deep	no	no
arg::body_part_ptr	sole	deep	no	yes
arg::grin_ptr	sole	deep	yes	yes
arg::auto_ptr	sole	reseat	no	no

Ownership

Not all smart pointers deal with management of the lifetime of the referenced object. However most of the ones in the above table do.

A smart pointer that owns the referenced object is responsible for destroying the object when its ownership is revoked. This happens, for example, when the pointer itself is destroyed, or when it receives ownership of a new object.

Copying

When a smart pointer is constructed from, or is assigned from another smart pointer then the references to objects that they hold will be manipulated.

Several possibilities exist - the value of the reference may be copied, the object referenced may be copied, or (in the case of auto_ptr) the reference may be reseated in the target pointer.

Incomplete Types

Since they destroy the referenced object - which may require a destructor call the majority of these smart pointers can only deal with complete types. (Where the compiler has seen the definition of the referenced object type.)

Because it was written to support the "Cheshire Cat" idiom grin_ptr does support working with incomplete types. (Actually, the type does need to be complete at the point of initialisation, but not elsewhere.)

Const-qualified

When writing a class that delegates all or part of its behaviour to an object referenced via a pointer it is desirable to maintain const-correctness. This does not happen with ordinary pointers as the const qualification of the pointer does not qualify the access to object.

The body_part_ptr and grin_ptr smart pointers support const-qualified access to the referenced object.

Downloading arglib

The library is supplied as sourcecode download arglib.

---

Copyright 1999-2000 Alan Griffiths