SynchroObject.h

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

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

#ifndef CNTM_SYNCHROOBJECT_H
#define CNTM_SYNCHROOBJECT_H
#include <Cntm/AsyncProc/Internal/ThreadProcFunctor.h>
#include <Cntm/AsyncProc/Internal/DeferProcFunctor.h>
#include <Cntm/Synchro/IBasicSynchro.h>
#include <Cntm/Synchro/SynchroSpace.h>
#include <Cntm/Synchro/ExtraSynchroSpace.h>

namespace Cntm
{

        class Sync;
        class ReentrantSync;
        
        /**
         * Базовый класс для синхрообъектов. Для того, чтобы создать свой класс синхрообъекта, его нужно унаследовать от классов Cntm::SynchroRefBase, Cntm::SynchroRefBaseEx или Cntm::SynchroAggregatedBase (эти объекты добавляют класс Cntm::SynchroObject как примесь к соответствующей реализации подсчета ссылок).
         * 
         * Синхрообъекты - это объекты со встроенными средствами синхронизации. Синхрообъект обязательно принадлежит определенному синхропространству (см. класс Cntm::SynchroSpace). Синхропространство задается при создании объекта и впоследствии не меняется.
         * 
         * Одна из важнейших функций синхрообъекта в многопоточных приложениях - эксклюзивный вход в синхропространство для выполнения действий, требующих синхронизации (т.е. они не должны быть прерваны другими действиями). Синхропространство в данном случае выступает как критическая секция или мьютекс, единая для всех объектов, принадлежащих синхропространству. Вход и выход из синхропространства выполняются методами Enter(), TryEnter() и Leave() или с помощью классов Cntm::Sync и Cntm::ReentrantSync (рекомендуется использовать классы, т.к. они повышают удобство и надежность). Вызов методов ...Enter() и Leave() аналогичен вызову соответствующих методов синхропространства. Процедуры входа в синхропространство рекурсивны. Принципы синхронизации описаны в классе Cntm::SynchroSpace.
         * 
         * Рекомендации по расположению точек входа в синхропространство. Если в системе используется только главное синхропространство и несколько потоков, то точки входа в синхропространство рекомендуется располагать в потоковых процедурах перед выполнением тех действий и вызовом тех методов, которые требуют синхронизации. Если в системе имеется несколько синхропространств, то вход в синхропространство рекомендуется делать в начале каждого интерфейсного метода (т.е. метода, который м.б. вызван из другого синхропространства), требующего синхронизации. Во внутренних методах (т.е. тех, которые непосредственно не вызываются из других синхропространств) делать точки входа в синхропространство не обязательно, т.к. эти методы вызываются уже из синхропространства. Пример:
         * \code
         * void Method1(int Arg)
         * {
         * Sync s(*this); // Точка входа в синхропространство до конца метода.
         * ...
         * }
         * \endcode
         * 
         * Дополнительно синхрообъект предоставляет методы для запуска асинхронных отложенных процедур (метод Defer()()) и асинхронных потоковых процедур (метод Thread()()). Асихронный означает, что поток выполнения не ожидает конца запущенной процедуры, а продолжает работу сразу же после запуска. Отложенная процедура - это  подготовленный вызов метода объекта (т.е. с указанием аргументов, которые будут переданы методу при вызове), который будет выполнен, когда будет возможен очередной вход в синхропространство. Асинхронные отложенные процедуры описаны в классе Cntm::AsyncProc. Реально отложенные процедуры реализованы через механизм отложенных синхрозаданий, описанный в документации по классу Cntm::SynchroSpace. Отложенные процедуры могут использоваться для синхронизированного вызова методов из разных потоков выполнения без входа в синхропространство. Асинхронная потоковая процедура - это метод объекта, который выполняется в отдельном потоке.  Потоковые процедуры также позволяют передавать любые аргументы в метод, который будет выполняться в отдельном потоке. Асинхронные потоковые процедуры описаны в классе Cntm::AsyncProc. Пример (асинхронный подсчет кол-ва слов в тексте):
         * \code
         * class Class1: public SynchroRefBase
         * {
         * int CalcWordsCount(const string& Text, const string& Delims) { ... return res; }
         * 
         * void Main()
         * {
         * string txt; cin >> txt;
         * AsyncProcResult<int> res = ThreadProc(&Class1::CalcWordsCount)(txt, " .,;:!?"); // Создание потока, выполняющего CalcWordsCount и передача ему текста txt и символов-разделителей.
         * ... // Выполнение каких либо полезных действий, например запись текста в файл.
         * cout << "Кол-во слов = " << res; // Вывод кол-ва слов на экран.
         * }
         * };
         * \endcode
         * 
         * При использовании синхрообъектов повышается удобство подключения к отложенным событиям (класс Cntm::DeferEvent) и вызов асинхронных отложенных процедур (методы Cntm::AsyncProc::Defer()()). Для работы этих средств требуется указание синхропространства, т.к. для синхрообъектов оно определено изначально, то нет нужды явно его указывать.
         * 
         * Синхронное создание объектов. Вызов конструктора синхрообъекта должен происходить внутри синхропространства, поэтому перед инициализацией объекта следует войти в то пространство, которому будет принадлежать объект. В качестве параметра конструктору передается синхропространство, к которому будет принадлежать объект. Имеется две формы конструкторов SynchroObject:
         * - первая форма явно принимает синхропространство. Она имеет вид: SynchroObject::SynchroObject(const SynchroSpace::Ptr& Space = SynchroSpace::Ptr()). Эта форма используется, когда операция создания синхрообъекта уже выполняется внутри пространства, к которому будет принадлежать новый объект. Если синхропространство не указано, то будет использовано главное синхропространство (т.о. если в программе используется только главное синхропространство, то нет необходимости указывать его явно). Если синхропространство явно не указано, а главное синхропространство отсутствует, то генерируется исключение Cntm::IllegalStateException.
         * - вторая форма принимает в качестве аргумента ссылку на объект синхросекции (классы Cntm::Sync или Cntm::ReentrantSync). Она имеет вид: SynchroObject::SynchroObject(Sync& ConstructSync) или SynchroObject::SynchroObject(ReentrantSync& ConstructSync). Эта форма используется, когда объект создается в новом или просто другом синхропространстве. В этом случае конструктор синхрообъекта пытается извлечь синхропространство из ConstructSync и если ConstructSync был проинициализирован, то использует извлеченное синхропространство. Если был указан пустой ConstructSync, то первым делом конструктор синхрообъекта создает дополнительное синхропространство (класс Cntm::ExtraSynchroSpace) и присваивает его ConstructSync (который передан по ссылке). Т.о. работа конструктора SynchroObject и конструкторов производных классов всегда будет осуществляться внутри синхпространства данного объекта.
         * 
         * Рекомендации по конструкторам пользовательских классов синхрообъектов. Если в системе используется только главное синхропространство, то никаких параметров использовать не нужно, объект автоматически будет принадлежать главному синхропространству. Если гарантируется, что объект будет создан внутри того синхропространства, к которому он будет принадлежать (обычно это внутренние объекты), то следует использовать только первую форму конструктора с явным указанием синхропространства. Если объект создается из произвольного синхропространства (в т.ч. из нового), то следует использовать вторую форму (возможно выбрав какую-то одну секцию, например, Sync). Если предполагается универсальное использование класса, то следует предоставить обе формы конструкторов (соответственно, три типа конструкторов). Примеры классов:
         * \code
         * // Класс, который создается в указанном синхропространстве.
         * class Class1: public SynchroRefBase
         * {
         * public:
         * typedef RefPtr<Class1> Ptr;
         * Class1(const SynchroSpace::Ptr& Space = SynchroSpace::Ptr()): SynchroRefBase(Space) {}
         * };
         * 
         * // Использование.
         * ...
         * Class1::Ptr c1 = new Class1; // Главное синхропространство.
         * ...
         * Class1::Ptr c2 = new Class1(this->Space()); // Явно указанное синхропространство, в него должен быть произведен вход перед использованием.
         * ...
         * 
         * // Класс, который создается в произвольном синхропространстве. Класс не использует реентерабельный вход, поэтому ограничимся только одной синхросекцией - Cntm::Sync.
         * class Class2: public SynchroRefBase
         * {
         * public:
         * typedef RefPtr<Class2> Ptr;
         * Class2(Sync& ConstructSync): SynchroRefBase(ConstructSync) {}
         * };
         * 
         * // Использование.
         * ...
         * Sync s;
         * Class2::Ptr c3 = new Class2(s); // Создает дополнительное синхрпространство, производит в него вход (заполняя s).
         * // На момент выхода из конструктора s будет содержать новое дополнительное синхропространство.
         * ...
         * Sync is(parent->Space()); // Войти в синхропространство.
         * Class2::Ptr c4 = new Class2(is); // Объект будет создан в синхропространстве parent->Space().
         * ...
         * \endcode
         * 
         * Синхронное уничтожение объектов. Подразумевает, что вызов деструкторов для классов Cntm::SynchroRefBase и Cntm::SynchroRefBaseEx и виртуального метода Cntm::SynchroRefBaseEx::OnReleaseInstance() будет производится отложенно синхронно по правилам для отложенных процедур или событий (см. выше) через механизм отложенных синхрозаданий (см. класс Cntm::SynchroSpace). Это значит, что вызов методов деинициализации будет происходить не в тот момент, когда будет утеряна последняя ссылка на объект, а когда можно будет осуществить отложенный синхронный вход в синхропространство, к которому принадлежал объект.
         * 
         * Данный класс обеспечивает многопоточность.
         * @author Овсеевич Р.
         * \ingroup Synchro
         */
        class SynchroObject: virtual public IBasicSynchro
        {
        public:
                
                typedef RefPtr<SynchroObject> Ptr;

                /**
                 * Возвращает синхропространство, к которому принадлежит синхрообъект. Результат не может принять значение NULL. 
                 */
                SynchroSpace::Ptr Space() const { return space; }

                /**
                 * Возвращает текущий режим входа в синхропространство. Возвращает true, если вход во !все! синхропространства, в которых поток выполнения находится в данный момент, был произведен в реентерабельном режиме. Если был хотя бы один вход в нереентерабельном режиме, то возвращается false.
                 * 
                 * Метод должен вызываться только после входа в синхропространство и в том же потоке, который произвел вход.
                 * 
                 * Вызывает Space()->IsReentrantMode().
                 */
                bool IsReentrantMode() const { return space->IsReentrantMode(); }
        
                /**
                 * Возвращает текущий режим входа в синхропространство. Возвращает true, если вход во !все! синхропространства, в которых поток выполнения находится в данный момент, был произведен в реентерабельном режиме. Если был хотя бы один вход в нереентерабельном режиме, то возвращается false.
                 * 
                 * Метод должен вызываться только после входа в синхропространство и в том же потоке, который произвел вход.
                 * 
                 * Вызывает Space()->Enter().
                 * @param ReentrantMode - режим входа (реентерабельный или нет). Описание режимов входа приведено в описании класса Cntm::SynchroSpace.
                 */
                void Enter(bool ReentrantMode = false) { space->Enter(ReentrantMode); }
        
                /**
                 * Возвращает текущий режим входа в синхропространство. Возвращает true, если вход во !все! синхропространства, в которых поток выполнения находится в данный момент, был произведен в реентерабельном режиме. Если был хотя бы один вход в нереентерабельном режиме, то возвращается false.
                 * 
                 * Метод должен вызываться только после входа в синхропространство и в том же потоке, который произвел вход.
                 * 
                 * Вызывает Space()->TryEnter().
                 * @param ReentrantMode - режим входа (реентерабельный или нет). Описание режимов входа приведено в описании класса Cntm::SynchroSpace.
                 */
                bool TryEnter(bool ReentrantMode = false) { return space->TryEnter(ReentrantMode); }
        
                /**
                 * Производит выход из синхропространства. Парный метод для Enter() и TryEnter() (когда последний вернул true). Параметр ReentrantMode должен иметь такое же значение, как и у парного ему метода Enter() и TryEnter().
                 * 
                 * Более подробное описание режимов входа и случаев, когда вход в синхропространство выполняется из другого синхропространства приведенов в описании класса Cntm::SynchroSpace.
                 * 
                 * Вызывает Space()->Leave().
                 * @param ReentrantMode - режим входа (реентерабельный или нет). Описание режимов входа приведено в описании класса Cntm::SynchroSpace.
                 */
                void Leave(bool ReentrantMode = false) { space->Leave(ReentrantMode); }

                /**
                 * Запустить асинхронную потоковую процедуру. Первым параметром указывается адрес метода, 
                 * который будет выполнен в новом потоке. Описание остальных параметров, возвращаемого 
                 * значения и принципов работы приведено в описании класса Cntm::AsyncProc и метода 
                 * Cntm::AsyncProc::Thread()(). После вызова метода Thread() в скобках указываются 
                 * передаваемые потоковой функции аргументы. Thread(...) может рассматриваться как 
                 * идентификатор функции, а вторая пара скобок - как ее вызов.
                 * 
                 * Пример:
                 * \code
                 * Thread(&Class1::Thread1)(Arg1, Arg2);
                 * Thread(&Class1::Thread2)();
                 * \endcode
                 */
                template < typename MethodSignatureT >
                SpecUtils::ThreadProcFunctor < typename SignatureInfo < MethodSignatureT > ::FuncSign > Thread(
                        MethodSignatureT Method,
                        BasicAsyncProc::ThreadPriority Priority = BasicAsyncProc::tpNormal,
                        bool HoldRef = true)
                {
                        return SpecUtils::ThreadProcFunctor<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                GenericMethodNoRefPtr<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                static_cast<typename SignatureInfo<MethodSignatureT>::ClassType*>(this), Method), Priority, HoldRef, false);
                }

                /**
                 * Запустить асинхронную отложеную процедуру. Первым параметром указывается адрес метода, 
                 * который будет выполнен в синхронно отложенно с использованием механизма отложенных 
                 * синхрозаданий (см. класс Cntm::SynchroSpace). Описание остальных параметров, 
                 * возвращаемого значения и принципов работы приведено в описании класса Cntm::AsyncProc
                 * и метода Cntm::AsyncProc::Defer()(). После вызова метода Defer() в скобках указываются 
                 * передаваемые отложенной функции аргументы. Defer(...) может рассматриваться как 
                 * идентификатор функции, а вторая пара скобок - как ее вызов.
                 * 
                 * Пример:
                 * \code
                 * Defer(&Class1::ShowMsg)(Arg1, Arg2);
                 * Defer(&Class1::Start)(); 
                 * \endcode
                 */
                template < typename MethodSignatureT >
                SpecUtils::DeferProcFunctor < typename SignatureInfo < MethodSignatureT > ::FuncSign > Defer(
                        MethodSignatureT Method,
                        bool HoldRef = true)
                {
                        return SpecUtils::DeferProcFunctor<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                GenericMethodNoRefPtr<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                static_cast<typename SignatureInfo<MethodSignatureT>::ClassType*>(this), Method), Space(), HoldRef, false);
                }

                /**
                 * Создать отсроченную асинхронную потоковую процедуру. Первым параметром указывается 
                 * адрес метода, который будет выполнен в новом потоке. Описание остальных параметров, 
                 * возвращаемого значения и принципов работы приведено в описании класса Cntm::AsyncProc 
                 * и метода Cntm::AsyncProc::SuspendThread()(). После вызова метода SuspendThread() в 
                 * скобках указываются передаваемые потоковой функции аргументы. SuspendThread(...) может
                 * рассматриваться как идентификатор функции, а вторая пара скобок - как ее вызов.
                 * 
                 * Пример:
                 * \code
                 * SuspendThread(&Class1::Thread1)(Arg1, Arg2);
                 * SuspendThread(&Class1::Thread2)();
                 * \endcode
                 */
                template < typename MethodSignatureT >
                SpecUtils::ThreadProcFunctor < typename SignatureInfo < MethodSignatureT > ::FuncSign > SuspendThread(
                        MethodSignatureT Method,
                        BasicAsyncProc::ThreadPriority Priority = BasicAsyncProc::tpNormal,
                        bool HoldRef = true)
                {
                        return SpecUtils::ThreadProcFunctor<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                GenericMethodNoRefPtr<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                static_cast<typename SignatureInfo<MethodSignatureT>::ClassType*>(this), Method), Priority, HoldRef, true);
                }

                /**
                 * Создать отсроченную асинхронную отложеную процедуру. Первым параметром указывается 
                 * адрес метода, который будет выполнен в синхронно отложенно с использованием механизма 
                 * отложенных синхрозаданий (см. класс Cntm::SynchroSpace). Описание остальных параметров, 
                 * возвращаемого значения и принципов работы приведено в описании класса Cntm::AsyncProc 
                 * и метода Cntm::AsyncProc::SuspendDefer()(). После вызова метода SuspendDefer() в скобках 
                 * указываются передаваемые отложенной функции аргументы. SuspendDefer(...) может 
                 * рассматриваться как идентификатор функции, а вторая пара скобок - как ее вызов.
                 * 
                 * Пример:
                 * \code
                 * SuspendDefer(&Class1::ShowMsg)(Arg1, Arg2);
                 * SuspendDefer(&Class1::Start)(); 
                 * \endcode
                 */
                template < typename MethodSignatureT >
                SpecUtils::DeferProcFunctor < typename SignatureInfo < MethodSignatureT > ::FuncSign > SuspendDefer(
                        MethodSignatureT Method,
                        bool HoldRef = true)
                {
                        return SpecUtils::DeferProcFunctor<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                GenericMethodNoRefPtr<typename SignatureInfo<MethodSignatureT>::FuncSign>(
                                static_cast<typename SignatureInfo<MethodSignatureT>::ClassType*>(this), Method), Space(), HoldRef, true);
                }

        protected:
                
                /**
                 * Конструктор используется, когда операция создания синхрообъекта уже выполняется внутри пространства, к которому будет принадлежать новый объект. Если синхропространство не указано, то будет использовано главное синхропространство (т.о. если в программе используется только главное синхропространство, то нет необходимости указывать его явно).
                 * 
                 * @param Space - (опционально) используется для задания синхропространства, к которому будет принадлежать создаваемый объект.
                 * 
                 * Исключение Cntm::IllegalStateException - если синхропространство явно не указано, а главное синхропространство отсутствует
                 */
                SynchroObject(const SynchroSpace::Ptr& Space = Cntm::SynchroSpace::Ptr());
                
                /**
                 * Конструктор используется, когда объект создается в новом или просто другом синхропространстве. В этом случае конструктор синхрообъекта пытается извлечь синхропространство из ConstructSync и если ConstructSync был проинициализирован, то использует извлеченное синхропространство. Если был указан пустой ConstructSync, то первым делом конструктор синхрообъекта создает дополнительное синхропространство (класс Cntm::ExtraSynchroSpace) и присваивает его ConstructSync (который передан по ссылке). Т.о. работа конструктора SynchroObject и конструкторов производных классов всегда будет осуществляться внутри синхпространства данного объекта.
                 * 
                 * @param ConstructSync - ссылка на синхросекцию, которая обеспечивает нахождение в синхропространстве при создании объекта.
                 */
                SynchroObject(Sync& ConstructSync);
                
                /**
                 * Конструктор используется, когда объект создается в новом или просто другом синхропространстве. В этом случае конструктор синхрообъекта пытается извлечь синхропространство из ConstructSync и если ConstructSync был проинициализирован, то использует извлеченное синхропространство. Если был указан пустой ConstructSync, то первым делом конструктор синхрообъекта создает дополнительное синхропространство (класс Cntm::ExtraSynchroSpace) и присваивает его ConstructSync (который передан по ссылке). Т.о. работа конструктора SynchroObject и конструкторов производных классов всегда будет осуществляться внутри синхпространства данного объекта.
                 * 
                 * @param ConstructSync - ссылка на реентерабельную синхросекцию, которая обеспечивает нахождение в синхропространстве при создании объекта.
                 */
                SynchroObject(ReentrantSync& ConstructSync);
                
                /**
                 * Деструктор. 
                 */
                virtual ~SynchroObject() {}

        private:

                friend class SynchroRefBase;
                friend class SynchroRefBaseEx;
                friend class SynchroDeleteTask;
                
                /**
                 * Класс синхрозадачи, которая выполняет операции деинициализации объекта. Ее выполнение состоит из вызова метода SynchroDeleteInstance удаляемого объекта.
                 * 
                 * Эта задача не реентерабельна.
                 * @author Овсеевич Р. 
                 */
                class SynchroDeleteTask: public SynchroSpace::TaskBase
                {
                public:

                        /**
                         * Конструктор.
                         */
                        SynchroDeleteTask(SynchroObject* DeletedObject): deletedObject(DeletedObject) {}

                        /**
                         * Выполнить задачу. Вызывает метод SynchroDeleteInstance() удаляемого объекта.
                         */
                        void Exec(bool Recursive) { deletedObject->SynchroDeleteInstance(); }

                        /**
                         * Задача не рекурсивная.
                         */
                        bool IsRecursive() const { return false; }
                        
                private:

                        /**
                         * Обычный указатель на удаляемую задачу.
                         */
                        SynchroObject* deletedObject;
                };

                
                /**
                 * Ссылочный указатель на синхропространство, к которому принадлежит синхрообъект. Не может принять значение NULL. 
                 */
                SynchroSpace::Ptr space;

                /**
                 * Виртуальный метод, вызываемый синхронно отложенно, после того, как объект перешел в удаляемое состояние. Реализации вызывают метод DeleteInstance() классов Cntm::RefBase и Cntm::RefBaseEx. 
                 */
                virtual void SynchroDeleteInstance() {}

                /**
                 * Запустить синхронный отложенный вызов метода SynchroDeleteInstance() через механиз отложенных синхрозаданий. Вызывается в момент перехода в удаляемое состояние из методов DeleteInstance() реализаций. 
                 */
                void CallSynchroDeleteInstance() { space->AddSynchroTask(new SynchroDeleteTask(this)); }                
        };

}

#endif //CNTM_SYNCHROOBJECT_H

---