ActiveObject.h

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

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

#ifndef CNTM_ACTIVEOBJECT_H
#define CNTM_ACTIVEOBJECT_H
#include <Cntm/SystemUtils/AtomicUtils.h>
#include <Cntm/Containers/Register.h>
#include <Cntm/RefCount/IRefObject.h>
#include <Cntm/RefCount/RefPtr.h>
#include <Cntm/Synchro/SyncScopes/Sync.h>
#include <Cntm/Synchro/SyncScopes/ReentrantSync.h>
#include <Cntm/ActiveObjects/Internal/BasicActiveThreadImpl.h>
#include <Cntm/ActiveObjects/ActiveThreadTerminatingSignal.h>
#include <Cntm/ActiveObjects/ActiveThread.h>

namespace Cntm
{

        /**
         * Активный объект - это объект, имеющий свои собственные потоки выполнения. Для того, чтобы 
         * создать свой класс активного объекта, его нужно унаследовать от классов Cntm::ActiveRefBase,
         * Cntm::ActiveRefBaseEx, Cntm::ActiveSynchroRefBase или Cntm::ActiveSynchroRefBaseEx (эти 
         * объекты добавляют класс Cntm::ActiveObject как примесь к соответствующей реализации 
         * подсчета ссылок или реализации синхронизации).
         * 
         * Средства, предоставляемые базовыми классами активных объектов - управление потоками 
         * активных объектов (класс Cntm::ActiveThread). Активные объекты могут создавать свои потоки 
         * с помощью метода Cntm::ActiveObject::StartThread()() или Cntm::ActiveThread::Start()(). В 
         * качестве потока выступает какой-либо метод объекта, которому при запуске можно передать 
         * любые аргументы. Потоки активных объектов являются единицами выполнения (класс 
         * Cntm::ActiveThread унаследован от Cntm::ExecutionUnit) и взаимодействие с потоками 
         * производится через хэндлы потоков (класс Cntm::ActiveThreadHandle), которые возвращаются 
         * как результат запуска. Как любая единица выполнения, поток активного объекта м.б. 
         * принудительно остановлен, для этого через хэндл ему посылается сигнал останова (процедуры 
         * останова подробно описаны в классе Cntm::ExecutionUnit).
         * 
         * Пример:
         * \code
         * class Class1: public ActiveSynchroRefBase
         * {
         *      ActiveThreadHandle hdl;
         * 
         *      void Thread1(int a, string s) { ... }
         * 
         *      void Start()
         *      {
         *              StartThread(&Class1::Thread1)(45, "Text");
         *              hdl = ActiveThread::Start(this, &Class1::Thread1)(45, "Text");
         *      }
         * };
         * \endcode
         * Активные объекты являются ссылочными объектами. Важной особенностью является то, что при 
         * создании потока активного объекта кол-во ссылок на объект не увеличивается. В этом состоит 
         * отличие потоков в активных объектах от асинхроных потоковых процедур AsyncProc::Thread()(), 
         * т.к. при выполнении асинхронных процедур держится ссылка на объект, поэтому, пока 
         * выполняется процедура, объект не может быть уничтожен. Второй важной функцией, которую 
         * предоставляет Cntm::ActiveObject, является автоматический останов потоков этого объекта 
         * перед уничтожением объекта. Когда на объект не осталось ссылок и он переходит в удаляемое 
         * состояние, всем потокам этого объекта автоматически посылается сигнал останова. 
         * Гарантируется, что деструктор (а для классов от Cntm::RefBaseEx и метод OnReleaseInstance()) 
         * будут вызваны только после завершения всех потоков (или иначе - все потоки (которые 
         * являются методами активного объекта) завершатся до вызова деструктора). Т.о. если нужен 
         * такой поток выполнения, который бы не блокировал уничтожение ссылочного объекта, а 
         * завершался, когда на объект не осталось ссылок, то для этого можно применять активные 
         * объекты и их потоки.
         * 
         * Выше говорилось, что поток активного объекта не создает новую ссылку на объект, а также, 
         * что поток завершаетмя после перехода объекта в удаляемое состояние (т.е. может 
         * выполняться, когда поток находится как в рабочем, так и в удаляемомм состоянии). Если 
         * потоку в процессе выполнения требуется ссылочный указатель на свой объект, то он его 
         * может получить из обычного, например, из this. При этом следует помнить, что если объект 
         * находится в удаляемом состоянии, то преобразование из обычного в ссылочный будет приводить 
         * к тому, что ссылочный указатель примет значение NULL.
         * 
         * Для того, чтобы объект при отсутствии на него ссылок смог уничтожиться, все его потоки 
         * должны остановиться. Для обнаружения сигнала останова в потоках можно использовать 
         * стандартные средства, предлагаемые классом Cntm::ActiveThread - 
         * Cntm::ActiveThread::Terminated() и Cntm::ActiveThread::CheckTerminating(). Первый просто 
         * возвращает значение флага останова потока, второй проверяет, и если он установлен, то 
         * генерирует специальное исключение Cntm::ActiveThreadTerminatingSignal.
         * 
         * Использование Using-объектов. Using-объекты (класс Cntm::Using, пакет Concurrency) - это 
         * scoped-объекты, наподобии auto_ptr и т.п., являющиеся по сути ссылочными указателями на 
         * активные объекты. Using-объекты преследуют 2 цели: 1 - при создании они проверяют флаг 
         * завершения потока и переданный ссылочный указатель на NULL (т.е. объект уже находится в 
         * удаляемом состоянии), если какое либо из этих условий истинно, то генерируется специальное 
         * исключение Cntm::ActiveThreadTerminatingSignal. 2 цель - хранить полученный ссылочный 
         * указатель на всем протяжении времени существования Using-объекта, т.о. гарантируется, что 
         * при выполнении кода, находящегося между созданием и деинициализацией Using-объекта 
         * активный объект не перейдет в удаляемое состояние. Для синхрообъектов имеются специальные 
         * Using-объекты, объединенные с синхросекциями - классы Cntm::UsingSync и 
         * Cntm::UsingReentrantSync, которые, кроме всего прочего, производят вход в 
         * синхропространство, к которому принадлежит активный синхрообъект. Пример метода 
         * активного объекта, выполняющегося в потоке:
         * \code
         * void Thread1(int a, string s)
         * {
         *      while (true) // Бесконечный цикл, в котором выполяниются повторяющиеся операции.
         *      {
         *              sleep(1);
         *              ...
         *              // Вход в Using-секцию. Либо вход будет успешный, либо, если поток 
         *              // необходимо завершить, то будет сгенерировано исключение 
         *              // ActiveThreadTerminatingSignal и произойдет завершение потока, т.к. 
         *              // оно не перехватывается внутри цикла. 
         *              Using use(*this);
         * 
         *              ... // В этом блоке объект всегда находится не в удаляемом состоянии и 
         *                      // преобразование обычного указателя (например, this) к ссылочному 
         *                      // никогда не приведет к результату NULL.
         * 
         *              // Выход из блока.
         *              use.Unuse(); 
         *              ...
         *              // Код, специфичный для синхрообъектов.
         *              // Вход в Using-секцию, в дополнение производится вход в синхропространство.
         *              UsingSync suse(*this);
         *              ... // Находимся в синхропространстве. Деинициализация произойдет в деструкторе suse.
         *      }
         * }
         * \endcode
         * В заключение приведем диаграмму, отражающую время жизни потока по отношению к времени жизни объекта:
         * \code
         * Жизнь объекта  - Жизнь потока
         * ----------------- Начало создания объекта.
         * |            _
         * |            |<-Запуск потока.
         * |            |
         * ----------------- Выход из метода запуска объекта, работа.
         * |            |
         * |            |
         * |            |<-Выполнение потока, когда объект находится в рабочем состоянии (на него есть ссылки).
         * |            |
         * |            |
         * ----------------- Переход объекта в удаляемое состояние (на него не осталось ссылок), потоку сообщается о завершении.
         * |            |
         * |            |<-Выполнение потока, когда объект находится в удаляемом состоянии.
         * |            |  Поток может узнать о завершении статическим методом ActiveThread::Terminated() или конструкцией Using.
         * |            |  После того как поток узнает о завершении он должен выполнить процедуру завершения.
         * |            |<-Завершающие действия потока, объект находится в удаляемом состоянии.
         * |            X
         * |
         * ----------------- Вызов деструктора или метода OnReleaseInstance когда запущенных потоков не осталось (для синхрообъектов - 
         * |                 когда будет возможен вход в синхропространство).
         * | 
         * |  Выполнение деинициализации объекта.
         * X
         * \endcode
         * 
         * Замечание по созданию потоков в конструкторе. Создавать потоки в конструкторе активного 
         * объекта нельзя, т.к. при создании потока временно создается ссылочный указатель на данный 
         * объект. Почему нельзя использовать ссылочные указатели на объект в его конструкторе 
         * рассмотрено в разделе "Подсчет ссылок".
         * 
         * Данный класс обеспечивает многопоточность.
         * @author Овсеевич Р.
         * \ingroup ActiveObjects
         */
        class ActiveObject: virtual public IRefObject
        {
        public:

                typedef RefPtr<ActiveObject> Ptr;

                /**
                 * Запустить поток для данного активного объекта.
                 * 
                 * После вызова метода StartThread() в скобках указываются аргументы, которые следует 
                 * передать запускаемому в новом потоке методу. Если аргументов нет, ставятся круглые 
                 * скобки. Если после вызова метода StartThread() не будет второй пары скобок, то поток 
                 * запущен не будет. Пример:
                 * \code
                 * StartThread(&Class1::Thread1)(45, "Text");
                 * StartThread(&Class1::Thread2)();
                 * \endcode
                 * Метод StartThread(...) олицетворяет идентификатор функции, а вторая пара скобок - его 
                 * вызов, поэтому когда говорится о методе StartThread()() и подобных ему, то указывается 
                 * две пары скобок.
                 * 
                 * Метод StartThread()() возвращает хэндл созданного потока (см. класс Cntm::ActiveThreadHandle).
                 * 
                 * Исключение: SystemException - системная ошибка при создании нового потока. 
                 * @param Method - указатель на метод активного объекта, который будет вызван в новом потоке.
                 * @param Priority - приоритет создаваемого потока. 
                 */
                template < typename MethodSignatureT >
                SpecUtils::ActiveThreadFunctor < typename SignatureInfo < MethodSignatureT > ::FuncSign > StartThread(
                        MethodSignatureT Method,
                        ActiveThread::ThreadPriority Priority = ActiveThread::tpNormal)
                {
                        return ActiveThread::Start(
                                static_cast<typename SignatureInfo<MethodSignatureT>::ClassType*>(this), Method, Priority);
                }
        
        protected:
                
                typedef Register<SpecUtils::BasicActiveThreadImpl::Ptr> ThreadsRegister;
                
                /**
                 * Конструктор по умолчанию 
                 */
                ActiveObject(): threadsCount(1) {}
                
                /**
                 * Деструктор. 
                 */
                virtual ~ActiveObject() {}
                
                /**
                 * Служебный виртуальный метод. Вызывается, когда все потоки завершились. В потомках 
                 * вызывает методы DeleteInstance() классов, реализующих подсчет ссылок. 
                 */
                virtual void AllThreadsFinished() = 0;
                
                /**
                 * Сообщить всем потокам об останове и перейти в режим ожидания завершения всех потоков 
                 * объекта.
                 * 
                 * Служебный метод. Когда все потоки будут завершены, вызовется AllThreadsFinished() для 
                 * дальнейшей деинициализации.
                 * 
                 * Данный метод вызывается при переходе объекта в удаляемое состояние из метода 
                 * DeleteInstance().
                 * 
                 * В промежутке от вызова TerminateAllThreads() до AllThreadsFinished() (состояние 
                 * ожидания завершения потоков) объект находится в удаляемом состоянии, поэтому 
                 * создание новых потоков невозможно.
                 */
                void TerminateAllThreads();
                                
        private:
        
                friend class SpecUtils::BasicActiveThreadImpl;
                
                /**
                 * Возвращает перечень, в котором регистрируются потоки. 
                 */
                ThreadsRegister& GetThreadsRegister() { return threadsRegister; }

                /**
                 * Вызывается перед запуском потока. Увеличивает счетчик кол-ва потоков. 
                 */
                void ThreadStarted() { threadsCount.Inc(); }

                /**
                 * Вызывает CheckAllThreadsFinished() для уменьшения счетчика кол-ва потоков и  его проверки. 
                 */
                void ThreadFinished() { CheckAllThreadsFinished(); }

        private:        

                /**
                 * Перечень потоков. При создании поток заносит туда свой собственный ссылочный указатель, 
                 * а когда завершается, то изымает его из перечня. 
                 */
                ThreadsRegister threadsRegister;                
                
                /**
                 * Кол-во потоков + 1. Атомарно прибавляется и отнимается 1 при создании и уничтожении 
                 * потоков. Дополнительно отнимается 1 в TerminateAllThreads(). Начальное значение 1.
                 */
                SpecUtils::AtomicVariable threadsCount;
                
                /**
                 * Уменьшает атомарный счетчик потоков. Когда счетчик достигает 0, вызывает 
                 * AllThreadsFinished(). Данный метод вызывается, когда завершается поток или объект 
                 * переходит в удаляемое состояние. Перед вызовом AllThreadsFinished() счетчик потоков 
                 * перводится в исходное значение - 1. 
                 */
                void CheckAllThreadsFinished();
        };

}

#endif //CNTM_ACTIVEOBJECT_H

---