SynchroSpace.h

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

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

#ifndef CNTM_SYNCHROSPACE_H
#define CNTM_SYNCHROSPACE_H
#include <boost/utility.hpp>
#include <Cntm/SystemUtils/SyncUtils.h>
#include <Cntm/SystemUtils/SysThreadIdentifier.h>
#include <Cntm/SystemUtils/SysThreadLocalInt.h>
#include <Cntm/Exceptions/NullArgException.h>
#include <Cntm/Utils/LinkedListItemBase.h>
#include <Cntm/RefCount/RefBase.h>
#include <Cntm/Synchro/IBasicSynchro.h>

namespace Cntm
{
        
        /**
         * Класс Cntm::SynchroSpace - базовый класс для синхропространств.
         * 
         * По своей сути синхропространство является критической секцией (мьютексом), синхронизирующей операции объектов, принадлежащих синхропространству (синхрообъектов, классы которых унаследованы от Cntm::Synchro...Base). Для того, чтобы при выполнении операции объекта в многопоточной среде не происходило гонок, такие операции должны выполняться внутри синхропространства, для чего поток выполнения должен войти в синхропространство. В каждый момент времени в синхропространстве может находится только один поток выполнения.
         * 
         * Существует 2 режима входа входа в пространство: реентерабельный и не реентерабельный. Сначала рассмотрим что такое реентерабельный (повторный) вход на примере оконной системы. Пусть у нас есть форма, есть периодический таймер и есть обаботчик сигнала от этого таймера. Пусть в этом обработчике мы отображаем модальное окно сообщения. Тогда если долго его не закрывать сработает таймер и снова будет вызван обработчик. Получится, что второй вызов произошел рекурсивно из той точки обработчика, где произведено отображение диалогового окна. В большинстве случаев это не страшно, однако в сложных системах может приводить к трудноуловимым ошибкам. Рекурсивным может быть вход не только в функцию, но и в объект, например, когда из метода, не закончившего до конца изменять данные, каким-то косвенным образом вызывается другой метод того же объекта, изменяющего те же самые данные, что может привести к ошибке. Для предотвращения таких ошибок следует использовать нереентерабельный режим входа в синхропространство, который блокирует возможность косвенного повторного входа в синхропространство. Конкретные аспекты будут рассмотрены для каждого типа синхропространств отдельно. Использование реентерабельного режима рекомендуется свести к минимуму.
         * 
         * Другое назначение синхропространства - выполнение отложенных синхрозаданий. Использование и выполнение этих заданий выглядит следующим образом. Поток выполнения создает задание и добавляет его в очередь (FIFO) заданий указанного синхропространства (при этом не важно произведен ли вход в указанное синхропространство или нет). После этого механизм синхропространства производит вход в это пространство (как только это будет возможно) в реентерабельном режиме (см. выше) и выполненяет задния из очереди, т.е. выполнение каждого задания начинается в реентерабельном режиме. Если добавление задания в синхропространство производится внутри этого пространства, то гарантируется, что выполнение заданий начнется только после выхода из этого синхропространства, т.е. при добавления заданий реентерабельный вход в пространство невозможен. При реентерабельном входе в синхропространство (например, при отображении модального окна) произойдет выполнение отложенных заданий.
         * 
         * Через механизм отложенных синхрозаданий работают такие компоненты системы как деинициализация синхрообъектов и отложенные события и процедуры.
         * 
         * Синхропространства можно поделить на главные (Cntm::...MainSynchroSpace) и дополнительные (Cntm::ExtraSynchroSpace). В системе может быть только одно главное синхропространство (на всем протяжении работы системы) и несколько дополнительных. Задачи дополнительных синхропространств описаны выше, задачи главного синхропространства несколько шире. К задачам главного синхропространства относится обеспечение жизненного цикла приложения. Под этим подразумевается, что оно запускает цикл обработки сообщений в главном потоке (или использует циклы других систем, например QT). Система работает, пока работает цикл, система переходит к завершению работы, когда произведен выход из цикла (пример: в QT запуск цикла производится методом QApplication::exec() - a.exec(), после выхода из которого система приступает к завершению работы). Важной особенностью главного синхропространства является то, что оно препятствует завершению работы, пока остается хотя бы один синхрообъект или одно синхропространство. Это повышает надежность завершающих операций, одновременно требует более четкой проектировки структуры объектов. Конкретное описание различных типов главных синхропространств см. в описании соответствующих классов Cntm::...MainSynchroSpace.
         * 
         * Замечания для случая нескольких синхропространств. Несколько синхропространств необходимо когда в системе выполняются длительные операции (например работа с пользовательским интерфейсом) и одновременно требуется быстрая реакция на какие-то события. В это случае следует разделить синхропространства на то, в котором будет производится медленная работа с пользовательским интерфейсом и дополнительное, которое будет обрабатывать события, требующие быстрой реакции. Не стоит без необходимости создавать лишние синхропространства. Когда имеется несколько пространств возможен вложенный вход, т.е. сначала произведен вход в одно пространство, а из него - в другое. Т.к. синхропространства по своей сути являются критическими секциями, то возможен случай смертильных объятий, когда один поток выполнения вошел в 1 пространство и ожидает входа во 2, а другой поток выполнения наоборот. Что бы этого избежать следует входить в синхропространства всегда в одном и том же порядке, другими словами, если составить граф, в котором вершинами будут синхропространства, а направленными дугами - порядок входа из одного пространства в другое, то такой граф не должен содержать циклов.
         * 
         * В заключение следует сказать, что методы синхропространства редко используются напрямую, обычно все операции выполняются через синхрообъекты.
         * 
         * Данный класс обеспечивает многопоточность.
         * @author Овсеевич Р. 
         * \ingroup Synchro
         */
        class SynchroSpace: public RefBase, virtual public IBasicSynchro, boost::noncopyable
        {
        protected:
                
                class TaskQueue;
                
        public:                 
        
                typedef RefPtr<SynchroSpace> Ptr;

                /**
                 * Базовый класс синхронной задачи. Система гарантирует, что методы задачи будут вызваны синхронно в том синхропространстве, куда она будет добавлена.
                 * 
                 * Выполнение задачи происходит отложенно от постановки задачи в очередь (т.е. если постановка задачи произошла внутри синхропространства, то выполнение начнется только после выхода из него) внутри синхропространства с реентерабельным режимом входа. Если в процессе выполнения задачи произойдет реентерабельный вход в механизм выполнения задач, то выполнение задач начнется с начала очереди.
                 * @author Овсеевич Р. 
                 */
                class TaskBase: LinkedListItemBase
                {
                public:
        
                        /**
                         * Вуртуальный деструктор. 
                         */
                        virtual ~TaskBase() {}
                        
                        /**
                         * Выполнить задачу. Если задача рекурсивная (IsRecurse() = true), то возможен повторный вход в данный метод (если при выполнении данного метода произойдет запуск вложенного цикла обработки задач).
                         * 
                         * Исключения, сгенерированные данным методом, игнорируются системой.
                         * @param Recursive - флаг, сообщающий какой это вызов: первый (false) или рекурсивный (true). 
                         */
                        virtual void Exec(bool Recursive = false) =0;
                        
                        /**
                         * Характеристика задачи, указывающая является ли задача рекурсивной или нет (постоянна на всем протяжении жизни объекта). Если возвращается false, то рекурсивных вызовов метода Exec() никогда не будет. Если возвращается true, то при запуске вложенного цикла обработки задач из данного метода опять будет вызван метод Exec() этого объекта (рекурсивно). 
                         */
                        virtual bool IsRecursive() const = 0;
                        
                private:

                        friend class TaskQueue;
                };

        
                /**
                 * Возвращает ссылочный указатель на объект главного синхропространства или NULL, если оно отсутствует. 
                 */
                static Ptr Main() { return mainFactory? mainFactory->QueryMainInstance() : Ptr(); }

                /**
                 * Возвращает ссылочный указатель на себя.
                 */
                SynchroSpace::Ptr Space() const { return this; }
                
                /**
                 * Возвращает текущий режим входа в синхропространство. Возвращает true, если вход во !все! синхропространства, в которых поток выполнения находится в данный момент, был произведен в реентерабельном режиме. Если был хотя бы один вход в нереентерабельном режиме, то возвращается false.
                 * 
                 * Метод должен вызываться только после входа в синхропространство и в том же потоке, который произвел вход. 
                 */
                bool IsReentrantMode() const;
        
                /**
                 * Производит вход в синхропространство. Если синхропространство занято другим потоком, то производит ожидание, пока другой поток не выйдет из синхропространства.
                 * 
                 * Допустим рекурсивный (повторный) вход из потока выполнения который уже находится в этом синхропространстве (возможно с другим режимом входа).
                 * 
                 * Более подробное описание режимов входа и случаев, когда вход в синхропространство выполняется из другого синхропространства приведенов в описании класса Cntm::SynchroSpace.
                 * 
                 * Вместо вызова метода Enter() и парного ему метода Leave() рекомендуется использовать классы Cntm::Sync и Cntm::ReentrantSync, которые обеспечивают более надежный и удобный способ вызова этих методов. Объекты этих классы производят вход в синхропространство от момента их создания до конца блока, в котором они объявлены.
                 * @param ReentrantMode - режим входа (реентерабельный или нет). Описание режимов входа приведено в описании класса Cntm::SynchroSpace.
                 */
                void Enter(bool ReentrantMode = false);
        
                /**
                 * Производит попытку входа в синхропространство. Если синхропространство занято другим потоком, то возвращает false, иначе входит в синхропространство и возвращает true. 
                 * 
                 * Допустим рекурсивный (повторный) вход из потока выполнения который уже находится в этом синхропространстве (возможно с другим режимом входа).
                 * 
                 * Более подробное описание режимов входа и случаев, когда вход в синхропространство выполняется из другого синхропространства приведенов в описании класса Cntm::SynchroSpace.
                 * 
                 * Вместо вызова метода TryEnter() и парного ему метода Leave() рекомендуется использовать классы Cntm::TrySync и Cntm::TryReentrantSync, которые обеспечивают более надежный и удобный способ вызова этих методов. Объекты этих классы производят вход в синхропространство от момента их создания до конца блока, в котором они объявлены.
                 * @param ReentrantMode - режим входа (реентерабельный или нет). Описание режимов входа приведено в описании класса Cntm::SynchroSpace. 
                 */
                bool TryEnter(bool ReentrantMode = false);
        
                /**
                 * Производит выход из синхропространства. Парный метод для Enter() и TryEnter() (когда последний вернул true). Параметр ReentrantMode должен иметь такое же значение, как и у парного ему метода Enter() и TryEnter().
                 * 
                 * Более подробное описание режимов входа и случаев, когда вход в синхропространство выполняется из другого синхропространства приведенов в описании класса Cntm::SynchroSpace.
                 * @param ReentrantMode - режим входа (реентерабельный или нет). Описание режимов входа приведено в описании класса Cntm::SynchroSpace. 
                 */
                void Leave(bool ReentrantMode = false);
        
                /**
                 * Добавить новую задачу в конец очереди. Объект задачи д.б. создан в динамической памяти. После выполнения задача автоматически будет удалена. Класс объекта задачи д.б. унаследован от Cntm:: SynchroSpace:: TaskBase. Если в процессе добавления задачи возникнет исключение, задача будет автоматически удалена.
                 * 
                 * Подробнее о синхрозадачах см. описание класса Cntm::SynchroSpace и Cntm::SynchroSpace::TaskBase.
                 * 
                 * Исключение: NullArgException если не указана задача.
                 * @param Task - задача, которую нужно выполнить. Объект задачи д.б. создан в динамической памяти. 
                 */
                virtual void AddSynchroTask(TaskBase* Task) = 0;
        
        protected:
        
                /**
                 * Виртуальный деструктор. 
                 */
                virtual ~SynchroSpace() {}

                /**
                 * Класс очереди задач для синхронного выполнения. Обеспечивает операции добавления задач и их синхронного выполнения. Перед добавлением необходимо создать объект (класс объекта д.б. унаследован от Cntm:: SynchroSpace:: TaskBase) в динамической памяти. После выполнения данный объект будет автоматически уничтожен очередью.
                 * 
                 * Данный класс является частично многопоточным. Вызовы Add синхронизированы друг с другом и с вызовом Exec(), вызовы Exec() друг с другом не синхронизированы, но м.б. рекурсивны.
                 * @author Овсеевич Р. 
                 */
                class TaskQueue: boost::noncopyable
                {
                public:
                
                        /**
                         * Конструктор. 
                         */
                        TaskQueue(): lastRecurseTask(TasksHead()), needExec(true) {}
                        
                        /**
                         * Добавить новую задачу в конец очереди. Объект задачи д.б. создан в динамической памяти. После выполнения задача автоматически будет удалена. Класс объекта задачи д.б. унаследован от Cntm:: SynchroSpace:: TaskBase.
                         * 
                         * Метод возвращает true, если на момент добавления очередь была пуста. Это значит, что после добавления необходимо запустить выполнение задач очереди. В противном случае возвращается false. Это означает, что запрос на выполнение очереди уже был поставлен ранее или уже идет выполнение.
                         * 
                         * Исключение: NullArgException если не указана задача.
                         * @param Task - задача, которую нужно выполнить. Объект задачи д.б. создан в динамической памяти. 
                         */
                        bool Add(TaskBase* Task);

                        /**
                         * Запустить задачи, находящиеся в очереди, на выполнение. После выполнения задача удаляется из очереди. Если при выполнении задачи происходит исключение, то оно игнорируется. 
                         */
                        void Exec() throw();
                        
                private:

                        /**
                         * Общая для всех очередей (статическая ) критическая секция, защищающая работу со списком задач. 
                         */
                        static SpecUtils::FastMutex mutex;

                        /**
                         * Голова (фиктивный эл-т) списка задач. 
                         */
                        LinkedListItemBase tasksHead;                   

                        /**
                         * Последняя рекурсивно выполняемая задача. Если выполнения нет (в т.ч. и после создания) указывает на голову (фиктивный эл-т) списка задач. 
                         */
                        TaskBase* lastRecurseTask;
                        
                        /**
                         * Флаг, требуется ли выполнение при добавлении задачи или нет.
                         */
                        bool needExec;
                        
                        /**
                         * Возвращает указатель на голову (фиктивный эл-т) списка задач, приведенный к TaskBase*. 
                         */
                        TaskBase* TasksHead() { return static_cast<TaskBase*>(&tasksHead); }

                        /**
                         * Возвращает слудующую задачу.
                         */
                        TaskBase* NextTask(TaskBase* Task)
                        {
                                return static_cast<TaskBase*>(Task->NextItem());
                        }                       
                };


                /**
                 * Интерфейс для фабрики класса, возвращающей указатель на объект главного синхропространства.
                 * 
                 * Фабрика должна быть зарегистрирована с помощью метода SetMainSynchroSpaceFactory. На всем протяжении программы допускается только одна фабрика, перерегистрация запрещена.
                 */
                class IMainSynchroSpaceFactory
                {
                public:
                        virtual ~IMainSynchroSpaceFactory(){}
                
                        /**
                         * Метод должен возвращать указатель на главное синхропространство или NULL, если такового не имеется.
                         */
                        virtual SynchroSpace::Ptr QueryMainInstance() = 0;
                };

                
                /**
                 * Установить фабрику для получения указателя на объект главного синхропространства. В системе может быть только одно главное синхропространство, и если оно уже установлено, то возвращается false. Метод должен вызываться из главного потока.
                 */
                static bool SetMainSynchroSpaceFactory(IMainSynchroSpaceFactory* Factory)
                {
                        if (mainFactory) return false;
                        mainFactory = Factory; // Сохраняем фабрику.
                        mainThreadId.Store(); // Запоминаем главный поток.
                        return true;
                }
                
                /**
                 * Возвращает true, если метод был вызван из главного потока (потока, который установил фабрику главного синхропространства) и false - в противном случае. 
                 */
                static bool IsMainThread() { return mainThreadId.Check(); }
                
                /**
                 * Выполнить вход в критическую секцию, связанную с синхропространством. 
                 */
                virtual void DoEnter() = 0;

                /**
                 * Выполнить попытку входа в критическую секцию, связанную с синхропространством. 
                 */
                virtual bool DoTryEnter() = 0;

                /**
                 * Выполнить выход из критической секции, связанную с синхропространством. 
                 */
                virtual void DoLeave() = 0;

        private:        

                /**
                 * Интерфейс для получения указателя на объект главного синхропространства. Он д.б. зарегистрирован при инициализации главного синхропространства. 
                 */
                static IMainSynchroSpaceFactory* mainFactory;           

                /**
                 * Идентификатор главного потока (потока, котрый зарегистрировал фабрику главного синхропространства). 
                 */
                static SpecUtils::SysThreadIdentifier mainThreadId;

                /**
                 * Счетчик реентерабельных входов, произведенных для конкретного потока выполнения. 
                 */
                static SpecUtils::SysThreadLocalInt reentrantCounter;           

                /**
                 * Счетчик нереентерабельных входов, произведенных для конкретного потока выполнения. 
                 */
                static SpecUtils::SysThreadLocalInt noReentrantCounter;

                /**
                 * Изменить значения счетчиков входа при входе и выходе из синхропространства. 
                 */
                void UpdateCounters(bool ReentrantMode, int Sign);
        };

}

#endif //CNTM_SYNCHROSPACE_H

---