RefBaseEx.h

См. документацию.

/*
 * CntmLib - Подсчет ссылок, потоки, синхронизация, асинхронные процедуры, события
 * Copyright (c) 2005, Овсеевич Роман, CntmLib@mail.ru
 * _______________________________________________________________________________
 * Разрешено свободное использование, копирование, распространение, изменение
 * (изменение сведений об авторских правах запрещено). Запрещена продажа и 
 * включение всей библиотеки или ее частей в другие библиотеки. В сведениях об
 * авторских правах на программу (или сведениях о программе, об авторах, 
 * использованных средствах разработки и т.д.) должна быть указана информация
 * о библиотеке CntmLib, ее авторе и, возможно, сайте или email'е.
 * Библиотека поставляется "как есть", без каких-либо гарантий со стороны автора.
 */ 

#ifndef CNTM_REFBASEEX_H
#define CNTM_REFBASEEX_H
#include <boost/limits.hpp>
#include <Cntm/SystemUtils/AtomicUtils.h>
#include <Cntm/Exceptions/IllegalStateException.h>
#include <Cntm/Exceptions/NullArgException.h>
#include <Cntm/RefCount/RefObjectUsedException.h>
#include <Cntm/RefCount/ForceDeleteRefObjectException.h>
#include <Cntm/RefCount/RefBase.h>

namespace Cntm
{

    /**
         * Более сложная реализация подсчета ссылок. Применяется в особых случаях, когда возможностей RefBase недостаточно. Кроме функциональности RefBase он обеспечивает расширенные средства по деинициализации объекта при уничтожении ссылок на него. Применяется в качестве базового класса или примеси для пользовательских классов, которые управляются подсчетом ссылок.
         * 
         * Особенности использования класса RefBaseEx в том, что он позволяет использовать ссылочные указатели в деструкторе и производить отложенное уничтожение.
         * 
         * Данный класс содержит виртуальный метод OnReleaseInstance(), который вызывается перед деструктором когда ссылок на объект не осталось и он переходит в удаляемое состояние. Этот метод может использоваться для запуска длительной асинхронной операции деинициализации объекта, например, в другом потоке. Чтобы обрабатывать это событие пользовательские классы должны переопределить этот метод. Реализация метода в RefBaseEx не выполняет ни каких действий.
         * 
         * Выше упоминалось, что при исчезновении ссылок на объект он переводится в удаляемое состояние, в котором подсчет ссылок не работает (см. IRefObject). В отличие от RefBase RefBaseEx позволяет вернуть объект из удаляемого состояние в рабочее, по сути дела начать новый цикл использования объекта. Для этого служит метод ReanimateInstance(). Данному методу передается ссылочный указатель, который инициализируется указателем на данный объект, после завершения метода кол-во ссылок устанавливается в 1 и появляется возможность использовать ссылочные указатели на данный объект. Когда все вновь созданные ссылки на данный будут утеряны, объект вновь перейдет в удаляемое состояние. Второй аргумент данного метода влияет на то, будет ли вызван метод OnReleaseInstance() при повторном переходе в удаляемое состояние (по умолчанию не будет).
         * 
         * Рассмотрим несколько сценариев использования:
         * 
         * 1. Использование ссылочных указателей в деструкторе. Для этого в деструкторе следует вызвать ReanimateInstance(), передав ему принимающий указатель, который после завершения метода будет указывать на данный объект. Второй аргумент функции не используется. После этого можно использовать ссылочные указатели на данный объект. Особенности данного сценария:
         * - когда счетчик ссылок достигнет 0, OnReleaseInstance вызываться не будет;
         * - после выхода из деструктора пользовательского класса ссылок на объект оставаться не должно. В противном случае для сигнализации о такой ошибке в деструкторе RefBaseEx будет сгенерировано исключение RefObjectUsedException для сигнализации о серьезной ошибке, которое будет автоматически перехвачено библиотекой.
         * 
         * 2. Отложенное уничтожение. Для этого следует переопределить метод OnReleaseInstance() и в нем вызвать ReanimateInstance(), передав первым параметром указатель, который будет указывать на данный объект, а вторым - флаг нужно ли вызывать OnReleaseInstance в следующий раз (если ничего не указывать, то вызова не будет). После этого можно передать указатель другим объектам для операций деинициализации или запустить поток, выполняющий эти действия. В последнем случае следует сохранять ссылочный указатель. Это можно обеспечить либо передачей указателя потоку как параметра или использовать поле класса. Перед завершением работы поток должен уничтожить или сбросить указатель в NULL. Особенности данного сценария:
         * - запрещается вручную удалять объект из метода OnReleaseInstance;
         * - когда счетчик ссылок повторно достигнет 0, будет опять вызван метод OnReleaseInstance() (если это явно указано при предыдущем вызове). Этот вызов может придти, когда первый OnReleaseInstance еще не завершил работу (например, если полученный указатель будет уничтожен в самом OnReleaseInstance() или фоновый поток закончит работу раньше, чем завершится первый OnReleaseInstance()).
         * - в случае повторных вызовов OnReleaseInstance() библиотека гарантирует, что деструктор объекта будет вызван после завершения работы всех вызывов OnReleaseInstance, даже если они вложены или выполняются параллельно.
         * 
         * Объекты классов, использующих RefBaseEx, должны размещаться только в динамической памяти, т.к. их поведение сильно связано с подсчетом ссылок, кроме того, принудительное удаление таких объектов запрещено (в деструкторе RefBaseEx будет сгенерировано исключение ForceDeleteRefObjectException, которое будет автоматически перехвачено библиотекой, сигнализирующее о неправильном использовании объекта).
         * 
         * Еще одно назначение класса RefBaseEx - блокировка завершения программы при наличие объектов, унаследованных от RefBaseEx. Более подробное описание этой возможности приведено в документации по методу WaitDestroyAll.
         * 
         * Данный класс обеспечивает многопоточность.
         * @author Овсеевич Р.
         * \ingroup RefCount
         */
        class RefBaseEx: public RefBase
        {
        public:

                /**
                 * Ожидание разрушения всех объектов, унаследованных от RefBaseEx, в течении MSecTimeout мсек. Если задержка не указана, то ожидание будет длиться бесконечно.
                 *
                 * Результат: true - все объекты уничтожились, false - некоторые объекты остались неуничтоженными.
                 * 
                 * Функцией можно пользоваться одновременно из нескольких потоков.
                 */
                static inline bool WaitDestroyAll(uint MSecTimeout = std::numeric_limits<uint>::max())
                {
                        return SpecUtils::RefObjectImplUtils::WaitDestroyAll(MSecTimeout);
                }       
        
        protected:

                /**
                 * Конструктор. Производит инициализацию объекта, устанавливает кол-во ссылок в 0. 
                 */
                RefBaseEx(): RefBase(), reanimateCounter(1), enableOnReleaseNotify(true)
                {
                        // Сообщаем о создании нового объекта с подсчетом ссылок
                        // для обеспечения ожидания уничтожения всех таких объектов.
                        SpecUtils::RefObjectImplUtils::IncRefObjectCount(this);
                }

                /**
                 * Виртуальный деструктор. Выполняет ряд проверочных действий.
                 * 
                 * Исключения:
                 * RefObjectUsedException - когда на объект еще имеются ссылки.
                 * ForceDeleteRefObjectException - когда произошла попытка принудительного удаления объекта.
                 * Эти исключения обрабатываются самой библиотекой и служат отладочным целям. 
                 */
                ~RefBaseEx()
                {
                        try
                        {
                                // Сообщаем об уничтожении объекта с подсчетом ссылок.
                                SpecUtils::RefObjectImplUtils::DecRefObjectCount(this);

                                // Попытка удалить объект вручную. В нормальном состоянии 
                                // reanimateCounter должен равняться 1 (перед деструктором 0 + 1).
                                if (!reanimateCounter.DecAndTest())
                                        throw ForceDeleteRefObjectException("Cntm::RefBaseEx::~RefBaseEx");
                        }
                        catch (...)
                        {
                        }
                }

                /**
                 * Перевести объект из удаляемого состояния, в которое он переходит при уничтожении всех ссылок на него, в рабочее. После вызова этого метода счетчик ссылок устанавливается в 1, становятся вновь доступны ссылочные указатели на данный объект. Если объект не в удаляемом состоянии, то производится установка RepeatOnRelease и возвращается ссылочный указатель.
                 * 
                 * Данный метод должен вызываться только из переопределенного виртуального метода OnReleaseInstance() или деструктора.
                 * 
                 * Параметры:
                 * Первый параметр этой функции - Dest - адрес ссылочного указателя, который принимает новый указатель на данный объект. Он не должен равняться NULL. Тип Dest является аргументом шаблона (ReanimateInstance - шаблонная функция), поэтому к нему выдвигается такое требование: он должен быть адресом ссылочного указателя на класс данного объекта или класс предка.
                 * Второй аргумент - RepeatOnRelease - разрешает или запрещает вызов метода OnReleaseInstance() при следующем переходе объекта в удаляемое состояние. Если он равен false, то будет сразу вызван деструктор, если true, сначала вызовется OnReleaseInstance(). По умолчанию параметр равен false.
                 * 
                 * Исключения:
                 * NullArgException - если первый параметр Dest равен NULL.
                 * BadArgException - если тип Dest'а не является типом ссылочного указателя на класс данного объекта или на класс его предка.
                 */
                template < typename T >
                void ReanimateInstance(RefPtr < T > * Dest, bool RepeatOnRelease = false)
                {
                        // Получающий указатель должен быть задан обязательно.
                        if (Dest == NULL) 
                                throw NullArgException("Cntm::RefBaseEx::ReanimateInstance", 
                                        "Указатель обязательно должен быть задан");

                        // Если объект в удаляемом состоянии, то реинициализируем кол-во 
                        // ссылок.
                        ReinitReferenceCounter();
                        *Dest = dynamic_cast<T*>(this);
                        
                        // Устанавливаем флаг повторных вызовов OnDeleteInstance(), увеличиваем 
                        // счетчик кол-ва текущих жизненных циклов.
                        enableOnReleaseNotify = enableOnReleaseNotify && RepeatOnRelease;                       
                        reanimateCounter.Inc();
                }

                /**
                 * Данный виртуальный метод вызывается когда объект переходит в удаляемое состояние, если его вызов не был запрещен в предыдущем вызове данного метода с помощью ReanimateInstance. Для обработки этого события пользовательский класс может переопределить метод.
                 * 
                 * Реализация этого метода для RefBaseEx не выполняет ни каких действий.
                 * 
                 * Все исключения, сгенерированные в переопределнном методе, будут проигнорированы. 
                 */
                virtual void OnReleaseInstance() {}

                /**
                 * Метод обработки события уничтожения последней ссылки на данный объект. Он позволяет либо запустить фоновый процесс уничтожения с длительными действиями, либо уничтожить объект.
                 * 
                 * Без крайней необходимости этот метод переопределять не рекомендуется.
                 */
                void DeleteInstance();

        private:

                /**
                 * Счетчик кол-ва текущих жизненных циклов.
                 */
                SpecUtils::AtomicVariable reanimateCounter;
                
                /**
                 * Разрешен ли вызов метода оповещения о возможности уничтожить объект.
                 */
                bool enableOnReleaseNotify;
        };

}

#endif //CNTM_REFBASEEX_H

---