Automatic Objects

Introduction

Traditional object-oriented design should change to allow for some of the newer features of the C++ language. Exceptions require all code to be re-evaluated. Many functions and objects no longer function properly if one assumes that exceptions may be thrown at any time. In order for code to remain deterministic, we must develop tools to help us write exception-safe code. One valid method is to wrap anything where an exception may occur in a try...catch statement. However, this method has the drawbacks of detracting from code readability and mainainability, and the levels of try..catch statements to perform even simple tasks in an exception-safe way quickly becomes unbearable. Having a try...catch...finally construct would alleviate some of the problem, but the levels of these constructs could still quickly become unbearable. Automatic objects are designed to help address this problem.

Inspiration: auto_ptr

The inspiration for creating a sub-class of objects comes from a single automatic object included in the Standard C++ Library, named the auto_ptr. The auto_ptr simply deletes whatever object it's pointing to. The auto_ptr can transfer its ownership to another auto_ptr through copy construction or the assignment operator.

The auto_ptr is incredibly useful; however, it would be nice if one had different automatic objects for different needs, so that by creating a local instance of that automatic object, one could then relax, knowing that the operation requested will be carried out when the object leaves scope no matter what.

Analysis of design

The design of the auto_ptr is governed by some simple guidelines:

• Simplicity. The auto_ptr is designed to do exactly one thing, and do it well. It is not a large or complicated object, and thus is less prone to errors.
• Forced Execution. The auto_ptr can be used as a way to force execution. For example, by returning an auto_ptr from a function (as opposed to returning a pointer to an object), one can force the calling function to eventually delete that object (unless the calling function invokes the Flexibility guideline -- see below).
• Ownership. The concept of ownership is designed into the auto_ptr. Each auto_ptr either owns its pointer or it does not. An auto_ptr that does not own its pointer ignores its pointer (does not delete it). This allows auto_ptr's to be passed into or returned from functions, or stored in data structures, etc., as well as being used within local function or object scope.
• Flexibility. The auto_ptr does not absolutely force execution; it does provide a means of giving up ownership, thus side-stepping the forced execution.
• Minimal Overhead. An auto_ptr is very resource-friendly. Its size is very small, and all functions are inlined for speed.

Definition of automatic objects

The simplest definition of an automatic object is an object that fulfils its purpose in its destructor. However, good programming practice for automatic objects require that they should follow the guidelines above. Namely:

• Simplicity. An automatic object should be designed to do only a few things. Sometimes it is useful to design an automatic object to do two things; usually one will suffice.
• Forced Execution. An automatic object should perform its action(s) in its destructor.
• Ownership. An automatic object should somehow encapsulate the concept of ownership, should transfer that ownership in a copy constructor and assignment operator, and should not perform any action(s) if unowned.
• Flexibility. An automatic object should provide a public member function to release ownership.
• Minimal Overhead. An automatic object should try to conserve system resources.

Introducing the auto_action

Terminology

• auto_action: an automatic object, used to perform an action
• default action: the action that the auto_action object is to perform
• bound object: the auto_action may be bound to an object, on which it performs the default action when necessary. The auto_action may also be unbound, in which case it does not perform its default action. (The "binding" is kept track of by an internal pointer, which may be 0 if unbound).

Design of auto_action

The auto_action class is designed to help in the construction of new automatic objects. It provides an inheritable interface for the concept and transfer of Ownership (through the use of a pointer), Forced Execution (performing the actions in the destructor), and Flexibility (through the use of the member function T * release(void);). It is templated on 1) the pointer type, 2) the function object that contains the actions to execute, and 3) the safety measures to be used when executing the action. It also fulfils the Simplicity and Minimal Overhead guidelines (all functions are inlined and non-virtual).

When deriving from auto_action, first create your function object, then your automatic object. Your function object should have a default constructor, unless you provide an instance of it from the constructor of your automatic object. Your automatic object should have a constructor that takes a pointer to T or constant pointer to T, defaulting to 0, and pass that to the constructor of auto_action.

auto_action Interface

template <typename T, typename TFunctionObject, typename Safetype = auto_action_safe>
class auto_action
{
  public:
    typedef T object_type;
    typedef TFunctionObject action_type;
    typedef Safetype safety_type;

    explicit auto_action(T * const NPtr = NULL, const TFunctionObject & NFunctionObject = TFunctionObject());
    auto_action(auto_action<T, TFunctionObject> & Other);
    ~auto_action();

    auto_action<T, TFunctionObject> & operator=(auto_action<T, TFunctionObject> & Other);

    T * release(void);
    T * get(void) const;
    const action_type & action(void) const;
    void execute(void);
    void reset(T * const NPtr = NULL);
    bool owns(void) const;
};

Template Arguments:

• T is the type of object that the auto_action may be bound to.
• TFunctionObject must be a function object that takes a single parameter of type 'T *' or 'T * const'. Any return value is ignored. Exceptions may be thrown. This object should execute whatever actions are necessary on the pointer. Function objects of this type are assumed to have a copy constructor of the form 'TFunctionObject(const TFunctionObject & Other)', an assignment operator of the form 'TFunctionObject & operator=(const TFunctionObject & Other)', and a destructor that may not ever throw exceptions.
• Safetype must be either 'auto_action_fast', 'auto_action_failsafe', or 'auto_action_safe'. These determine the actions to be taken if the function object throws an exception:
  • auto_action_fast may be used if it is well-known that the function object cannot throw an exception. It provides no exception handling, and allows the exception to propogate.
  • auto_action_failsafe will catch (and ignore) all exceptions thrown by the function object.
  • auto_action_safe (the default) will catch and ignore all exceptions thrown by the function object, but only if there is another exception that has been thrown and not yet caught; if there is no uncaught exception, then this option will allow any exception thrown by the function object to propogate.

A word on Safetype

One of the main uses for auto_action objects is so that actions will always be executed, even in code that may throw exceptions. auto_action_safe is almost always the best choice, because if an exception is thrown during stack unwinding, terminate() is called. Only use auto_action_fast if you are sure that the function object cannot throw exceptions, or that it will not be called during stack unwinding, and you are willing to bet the well-being of your program on it :)

Typedefs:

• object_type is the type of object that the auto_action may be bound to.
• action_type is the function object type of the default action.
• safety_type is the Safetype level requested.

Constructors:

• auto_action(T * const NPtr = 0, const TFunctionObject & NFunctionObject = TFunctionObject()) will construct a new auto_action with default action NFunctionObject and bound to NPtr unless NPtr is 0, in which case the auto_action is unbound.
• auto_action(auto_action<T, TFunctionObject> & Other) will construct a new auto_action with a default action equal to Other's default action, and bound to Other's pointer (if Other is unbound, the new auto_action is also unbound). Other is then unbound.

Destructor:

• ~auto_action() if the auto_action is bound, the destructor will execute the default action.

Copy Constructor:

• auto_action<T, TFunctionObject> & operator=(auto_action<T, TFunctionObject> & Other) will execute the following sequence of actions:
  1. If the auto_action is bound, the default action is executed. If the action throws an exception and the Safetype level allows it to propogate, the exception is propogated here as well, causing the assignment to be cancelled.
  2. The auto_action's default action is set to Other's default action and the auto_action is bound to Other's pointer (if Other is unbound, the auto_action is also unbound).
  3. Other is unbound.
  4. *this is returned.

Member Accessors:

• T * get(void) const returns the internal pointer to the bound object, or 0 if the auto_action is unbound.
• action_type action(void) const returns the default action.

Member Functions:

• T * release(void) unbinds the auto_action. Returns the object that this auto_action was previously bound to.
• void execute(void) executes the default action in such a way that exceptions may be thrown and that the auto_action is always unbound. Precondition: owns()
• void reset(T * const NPtr = 0) will execute the following sequence:
  1. If the auto_action is bound, the default action is executed. If the action throws an exception and the Safetype level allows it to propogate, the exception is propogated here as well, cancelling the reset.
  2. The auto_action is bound to NPtr, or if NPtr is 0, the auto_action is unbound.
• bool owns(void) const will return true if the auto_action is bound, or false if unbound. Semantically equivalent to '(get() != 0)'.

A simple example: autoNULL

This is an automatic object that binds to a pointer, and its action is to set that pointer to 0. It is used to make sure that a pointer is set to 0 whenever a scope exits.

namespace details {

template <typename T>
struct autoNULL_FunctionObject
{
  void operator()(T * Ptr) { *Ptr = 0; }
};

} // namespace details

template <typename T, typename Safetype = auto_action_safe>
struct autoNULL: public auto_action<T *,
    details::autoNULL_FunctionObject<T *>, Safetype>
{
  typedef auto_action<T *,
      details::autoNULL_FunctionObject<T *>, Safetype> parent_type;
  explicit autoNULL(T ** const NPtr = 0):parent_type(NPtr) { }
};

First we define the function object. We put it into namespace 'details' to avoid namespace pollution. It is a simple object, that is templated on a type T (which will always be a pointer type), and sets its argument to 0.

Then we define the automatic object type itself. We allow the user to determine what type of pointer to set to 0. (In this case, T is not necessarily a pointer type), and inform auto_action (through the template parameters) that we are holding a pointer to a pointer, and our particular function object type.

All automatic objects must explicitly provide all constructors. It is customary to provide a default constructor that creates an unbound automatic object. Our example constructor satisfies the binding and unbinding constructions. Like many automatic objects, we use the default function object.

autoNULL inherits concepts of ownership, the execution of the action in the destructor, etc. all from auto_action.

Example of usage:

extern int * x;
void func(void)
{
  // ... (1)
  autoNULL x_guard(&x);
  // ... (2)
}

Simple Automatic Objects

An automatic object is simple if it satisfies the following:

• It has only one action.
• This action is a member function of the templated class which takes no arguments and returns void.

Furthermore, simple automatic objects follow some conventions:

• The name of the automatic object type is auto_action, where action is its action name.
• The automatic object type is templated on the actual class that it can bind to. The only restriction is that that class must have a member function named action which returns void and takes no arguments.
• The automatic object type is also templated on a Safetype parameter, which defaults to auto_action_safe.
• The automatic object type provides an additional member function, named action, which is a synonym for 'execute()'.
• The automatic object's constructor takes an optional pointer, which if 0 or not provided, indicates the automatic object is to be unbound.

Simple automatic objects are fairly common, and for that reason a macro is provided: BOOST_AUTOACTION_DEFINE_SIMPLE(PrimaryActionName) simplifies defining simple automatic objects. :)

#define BOOST_AUTOACTION_DEFINE_SIMPLE(PrimaryActionName) \
template <typename T, typename Safetype = ::boost::auto_action_safe> \
struct auto_ ## PrimaryActionName : \
    public ::boost::auto_action<T, ::std::mem_fun_t<void, T>, Safetype> \
{ \
  typedef ::boost::auto_action<T, ::std::mem_fun_t<void, T>, Safetype> parent_type; \
  explicit auto_ ## PrimaryActionName(T * const NPtr = 0) \
  :parent_type(NPtr, ::std::mem_fun_t<void, T>(&(T::PrimaryActionName))) { } \
  void PrimaryActionName (void) { execute(); } \
  auto_ ## PrimaryActionName & operator=(auto_ ## PrimaryActionName & Other) \
  { \
    parent_type::operator=(Other); \
    return *this; \
  } \
}

Example of usage:

BOOST_AUTOACTION_DEFINE_SIMPLE(pop);

extern std::stack<int> s;

void func(void)
{
  s.push(13);
  auto_pop<std::stack<int> > s_guard(&s);
  // ... (1)
  s_guard.pop(); // or "s_guard.execute();" (2)
  // ... (3)
}

Recommended Usage

Automatic objects are especially useful in the following situations:

• Dealing with library code that is unclear in its documentation of when exceptions may be thrown.
• Dealing with any kind of a transaction system; for example, a database, which requires whenever possible all transactions be either rolled back or committed.
• Dealing with multi-threaded synchronization; for example, an auto_Unlock object may make sure that a mutex is unlocked when a function is exited, even if an exception is thrown.