coherence/lang/FinalizableBlock.hpp

/*
* FinalizableBlock.hpp
*
* Copyright 2001-2008 by Oracle. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_FINALIZABLE_BLOCK_HPP
#define COH_FINALIZABLE_BLOCK_HPP

#include <stddef.h>

#include "coherence/lang/compatibility.hpp"

COH_OPEN_NAMESPACE2(coherence,lang)


/**
* A finalizable block which runs a series of chained Finalizers as part of
* its destruction.
*
* FinalizableBlocks are useful for cases where a series of finalization
* routines need to be run from a nested function calls. For non-nested
* finalization the use of a FinalizableBlock is unnecessary, and a disposable
* or local class should be used.
*/
class COH_EXPORT FinalizableBlock
    {
    // ----- constructors ---------------------------------------------------

    protected:
        /**
        * Construct a FinalizableBlock object.
        *
        * @param pDelegate  FinalizableBlock to delegate to, or NULL for
        *                   no delegate
        */
        FinalizableBlock(FinalizableBlock* pDelegate = NULL);

        /**
        * Copy constructor.
        *
        * The new block takes over the ownership of the finalization, the
        * supplied block is invalidated, and is not longer useable.
        *
        * @see COH_FINALIZABLE
        */
        FinalizableBlock(const FinalizableBlock& that);

        /**
        * Destroy a FinalizableBlock object.
        *
        * In the case of delegating blocks the destructor has no effect,
        * otherwise the finalizer stack is popped, until until all finalizers
        * have been deleted.
        */
        ~FinalizableBlock();


    // ----- operators ------------------------------------------------------

    public:
        /*
        * Boolean conversion for use in COH_FINALIZABLE macro.
        *
        * @return false always
        */
        operator bool() const;

    private:
        /**
        * Blocked assignement operator.
        */
        const FinalizableBlock& operator=(const FinalizableBlock&);


    // -------- nested class: Finalizer -------------------------------------

    public:
        /**
        * Interface for custom automatic cleanup operations.
        */
        class COH_EXPORT Finalizer
            {
            // ----- constructor/destrutor -----------------------------

            public:
                /**
                * Finalizer constructor.
                */
                Finalizer();

                /**
                * Finalizer destructor.
                */
                virtual ~Finalizer();


            // ----- data members --------------------------------------

            private:
                /**
                * Pointer to the next Finalizer on the stack.
                */
                Finalizer* m_pNext;


            // ----- friends -------------------------------------------

            friend class FinalizableBlock;
            };


    // ----- FinalizableBlock interface -------------------------------------

    public:
        /**
        * Push a custom finalizer onto the FinalizableBlock's
        * finalization stack.
        *
        * If the FinalizableBlock was constructed with a delegate,
        * then the finalizer is pushed on the delegates finalizer stack.
        *
        * The finalizer will then be owned by the FinalizableBlock and will
        * be automatically deleted with the top-most FinalizableBlock is
        * destroyed.
        *
        * @param pFinalizer  finalizer to add to the finalization stack
        */
        void pushFinalizer(Finalizer* pFinalizer);

    protected:
        /**
        * Return true if the FinalizableBlock is not delegating to
        * another FinalizableBlock.
        *
        * @return return true if the FinalizableBlock is not delegating
        *         to another FinalizableBlock
        */
        bool isTerminal() const;

        /**
        * Initialize a FinalizableBlock object.
        *
        * A block may be re-initialized so long as it has not been assigned a
        * delegate, and has no finalization stack.
        *
        * @param pDelegate  FinalizableBlock to delegate to, or NULL for
        *                   no delegate
        */
        void initialize(FinalizableBlock* pDelegate = NULL);


    // ----- data members ---------------------------------------------------

    private:
        /**
        * If non-NULL specified a FinalizableBlock to delegate to.
        */
        mutable FinalizableBlock* m_pDelegate;

        /**
        * The head of the finalizer stack.
        */
        mutable Finalizer* m_pFinalizerHead;
    };

COH_CLOSE_NAMESPACE2

/**
* Macro for making more readable finalizable code blocks See the
* documentation of FinalizableBlock for a useage example.
*
* The macro will create a well known FinalizableBlock instance referenceable
* as "finally".
*
* @see coherence::lang::FinalizableBlock
*/
#define COH_FINALIZABLE() \
    if (coherence::lang::FinalizableBlock finally \
        = coherence::lang::FinalizableBlock()) \
        { \
        COH_THROW(coherence::lang::IllegalStateException::create()); \
        } \
    else

#endif // COH_FINALIZABLE_BLOCK_HPP

Copyright (c) 2000-2008 Oracle. All rights reserved.