MainSynchroSpace.h

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

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

#ifndef CNTM_MAINSYNCHROSPACE_H
#define CNTM_MAINSYNCHROSPACE_H
#include <boost/thread/recursive_mutex.hpp>
#include <Cntm/Synchro/SynchroSpace.h>
#include <Cntm/SystemUtils/SysCriticalSection.h>
#include <Cntm/SystemUtils/SysSignalFlag.h>

namespace Cntm
{

        /**
         * Класс главного синхропространства. Описание понятия синхропространства приведено в SynchroSpace.
         * 
         * Для обработки синхронных задач используется главный поток.
         * 
         * Обеспечение жизненного цикла приложения. Для обеспечения жизненного цикла применяется метод Run(). Также в нем реализован цикл обработки синхронных заданий. В общем случае жизненный цикл выглядит следующим образом.
         * \code
         * int main(args...)
         * {
         *      Cntm::MainSynchroSpace::Begin();
         *      ...
         *      Инициализация
         *      ...
         *      Cntm::MainSynchroSpace::Run();
         *      ...
         *      Деинициализация
         *      ...
         *      Cntm::MainSynchroSpace::End();
         *      return 0;
         * }
         * \endcode
         * 
         * Метод Begin() производит создание и подготовку главного синхропространства. Далее следует инициализация системы, после чего методом Run() запускается приложение - это и является жизненным циклом приложения. После завершения работы (методом Stop()) происходит деинициализация и выход из главного синхропространства - метод End(). Данный метод производит ожидание момента, когда будут уничтожены все синхрообъекты в системе. В процессе ожидания синхропространство может обрабатывать синхронные задачи.
         * 
         * Замечание. В интервале от метода Begin() до входа в цикл методом Run(), от выхода из цикла до входа в следующий цикл, от выхода из цикла до метода End() главный поток выполнения находится внутри синхропространства.
         * 
         * Существует более простая и удобная структура приложения:
         * \code
         * int main(args...)
         * {
         *      Cntm::MainSynchroSpace::Application a;
         *      ...
         *      Инициализация
         *      ...
         *      a.Run();
         *      ...
         *      Деинициализация
         *      ...
         *      return 0;
         * }
         * \endcode
         * 
         * Замечание по реентерабельности. Данный тип синхропространства запрещает реентерабельный вход в синхропространство. Поэтому разница между реентерабельным и не реентерабельным режимами отсутствует.
         * @author Овсеевич Р.
         * \ingroup Synchro
         */
        class MainSynchroSpace : public SynchroSpace
        {
        public:
                
                typedef RefPtr<MainSynchroSpace> Ptr;

                /**
                 * Класс приложения. Предназначен для автоматизации вызывов MainsynchroSpace::Begin() (вызывается в конструкторе), MainsynchroSpace::End() (вызывается в деструкторе).
                 * @author Овсеевич Р.
                 * \ingroup Synchro
                 */
                class Application
                {
                public:

                        /**
                         * Конструктор. Выполняет операцию Cntm::MainsynchroSpace::Begin().
                         */
                        Application() : ended(false)
                        {
                                MainSynchroSpace::Begin();
                        }

                        /**
                         * Деструктор. Выполняет операцию Cntm::MainsynchroSpace::End() если ранее не был вызван метод End().
                         */
                        ~Application() { End(); }

                        /**
                         * Запустить жизненный цикл приложения и обработку синхронных заданий. Выполняет операцию Cntm::MainsynchroSpace::Run()
                         */
                        void Run() { MainSynchroSpace::Run(); }
                        
                        /**
                         * Метод позволяет выполнить операцию Cntm::MainsynchroSpace::End() до уничтожения объекта приложения. Повторные вызовы данного метода ничего не делают.
                         */
                        void End()
                        {
                                if (ended) return;
                                MainSynchroSpace::End();
                                ended = true;
                        }
                        
                private:
                
                        /**
                         * Флаг: был ли уже вызван метод End() или нет.
                         */
                        bool ended;
                };

        
                /**
                 * Добавить новую задачу в конец очереди. Объект задачи д.б. создан в динамической памяти. После выполнения задача автоматически будет удалена. Класс объекта задачи д.б. унаследован от SynchroSpace::TaskBase.
                 * 
                 * Подробнее о синхрозадачах см. описание класса SynchroSpace и SynchroSpace::TaskBase.
                 * 
                 * Система гарантирует, что задача будет выполнена в контексте главного потока синхронно с прочими событиями библиотеки QT.
                 * 
                 * \throw NullArgException если не указана задача.
                 * @param Task - задача, которую нужно выполнить. Объект задачи д.б. создан в динамической памяти. 
                 */
                void AddSynchroTask(TaskBase* Task) { implement->AddSynchroTask(Task); }
        
                /**
                 * Создание и вход в главное синхропространство. Поток, вызвавший этот метод считается главным потоком приложения.
                 * 
                 * Вместо вызова этого метода рекомендуется использовать класс MainSynchroSpace::Application.
                 * 
                 * \throw IllegalStateException при попытке повторного создания главного синхропространства (главное синхропространство этого же или другого типа уже создано).
                 */
                static void Begin();
        
                /**
                 * Запустить жизненный цикл приложения и обработку синхронных заданий. Метод будет выполняться до тех пор, пока приложение не будет остановлено методом Stop().
                 * 
                 * Данный метод должен вызываться из главного потока приложения.
                 * 
                 * Допустимо несколько последовательных вызовов данного метода. Поведение при последующих вызовах ничем не отличается от первого вызова.
                 * 
                 * \throw LoopInNoMainThreadException - при попытке запуска цикла обработки сообщений не из главного потока
                 * \throw NoReentrantModeException - при попытке реентерабельного входа в синхропространство (рекурсивный вызов данного метода)
                 */
                static void Run() { implement->Run(); }

                /**
                 * Выход из главного синхропространства. Метод производит ожидание уничтожения всех синхрообъектов и синхропространств. В процессе ожидания запускается цикл обработки событий.
                 * 
                 * \throw LoopInNoMainThreadException - при попытке завершения работы не из главного потока
                 */
                static void End() { implement->Finish(); }

                /**
                 * Остановить выполнение приложения. Вызов метода действует на текущий или последующий запуск метода Run(). 
                 */
                static void Stop() { implement->Stop(); }
        
        protected:
                
                friend class Implement;
                
                /**
                 * Деструктор. 
                 */
                ~MainSynchroSpace() { implement->MainInstanceDeleted(this); }

                /**
                 * Выполнить вход в критическую секцию, связанную с синхропространством.
                 */
                void DoEnter() { implement->DoEnter(); }

                /**
                 * Выполнить вход в критическую секцию, связанную с синхропространством.
                 */
                bool DoTryEnter() { return implement->DoTryEnter(); }

                /**
                 * Выполнить вход в критическую секцию, связанную с синхропространством.
                 */
                void DoLeave() { implement->DoLeave(); }

private:
        
                /**
                 * Класс, реализующий все функции синхропространства (вход в синхропространство, выполнение синхронных задач), созданием объекта синхропространства и ожидания его уничтожения.
                 * @author Овсеевич Р. 
                 */
                class Implement: public SynchroSpace::IMainSynchroSpaceFactory
                {
                public:
        
                        /**
                         * Конструктор.
                         * 
                         * Исключение: IllegalStateException при попытке повторного создания главного синхропространства.
                         */
                        Implement();
                        
                        /**
                         * Реализация метода Cntm::SynchroSpace::IMainSynchroSpaceFactory::QueryMainInstance.
                         */
                        SynchroSpace::Ptr QueryMainInstance();
                        
                        /**
                         * Выполнение захвата критической секции.
                         * 
                         * Вызывается из QTMainSynchroSpace::DoEnter().
                         */
                        void DoEnter() { critSection.Enter(); }
        
                        /**
                         * Выполнение попытки захвата критической секции.
                         * 
                         * Вызывается из QTMainSynchroSpace::DoTryEnter().
                         */
                        bool DoTryEnter() { return critSection.TryEnter(); }
        
                        /**
                         * Выполнение выхода из критической секции.
                         * 
                         * Вызывается из QTMainSynchroSpace::DoLeave().
                         */
                        void DoLeave() { critSection.Leave(); }
        
                        /**
                         * Добавить новую синхронную задачу. Добавляет задачу в очередь и высталяет сигнальный флаг.
                         * 
                         * Вызывается из MainSynchroSpace::AddSynchroTask().
                         * 
                         * Исключение: NullArgException если не указана задача.
                         * @param Task - задача, которую нужно выполнить. Объек задачи д.б. создан в динамической памяти. 
                         */
                        void AddSynchroTask(SynchroSpace::TaskBase* Task)
                        {
                                if (taskQueue.Add(Task))
                                        signalFlag.Set();
                        }
        
                        /**
                         * Метод запуска. Выполняет вход в крит. секцию.
                         * 
                         * Вызывается из MainSynchroSpace::Begin().
                         */
                        void Start();
                        
                        /**
                         * Запуск жизненного цикла и обработка синхронных задач.
                         * 
                         * Вызывается из MainSynchroSpace::Run().
                         */ 
                        void Run();                     

                        /**
                         * Метод ожидает уничтожения всех синхрообъектов (последним уничтожается главное синхропространство).
                         * 
                         * Вызывается из QTMainSynchroSpace::End().
                         */
                        void Finish();
                        
                        /**
                         * Остановить выполнение жизненного цикла.
                         * 
                         * Вызывается из QTMainSynchroSpace::Stop().
                         */
                        void Stop();

                        /**
                         * Метод сбрасывает указатель на текущее синхропространство.
                         * 
                         * Вызывается из MainSynchroSpace::~MainSynchroSpace().
                         */
                        void MainInstanceDeleted(MainSynchroSpace* Inst);

                private:

                        /**
                         * Критическая секция данного синхропространства.
                         */
                        SpecUtils::SysCriticalSection critSection;
                        
                        /**
                         * Сигнальный флаг для пробуждения цикла обработки синхронных задач.
                         */
                        SpecUtils::SysSignalFlag signalFlag;
                        
                /**
                 * Крит. секция, защищающая работу с указателем instance (получение из instance ссылочного указателя, создание нового объекта синхропространства, сброс указателя instance).
                 */
                        boost::recursive_mutex instanceMutex;                   
                        
                        /**
                         * Указатель на синхропространство QT. Инициализируется при создании синхропространства QT и сбрасывается в NULL в деструкторе синхропространства.
                         */
                        SynchroSpace* instance;
                        
                        /**
                         * Ссылочный указатель на синхропространство. Инициализируется в конструкторе (в начале выполнения программы) и сбрасывается в методе Finish() (в конце выполнения).
                         * 
                         * Используется для минимизации созданий объектов синхропространств QT, а также, чтобы избежать преждевременного выхода из цикла обработки событий (если во время работы, когда отображено главное окно будут потеряны ссылки на синхропространство, то произойдет преждевременный выход).
                         */
                        SynchroSpace::Ptr holdInstance;
                        
                        /**
                         * Флаг останова.
                         */
                        volatile bool stopping;
                        
                        /**
                         * Флаг запущенности.
                         */
                        volatile bool runned;
                        
                        /**
                         * Очередь синхронных задач.
                         */
                        TaskQueue taskQueue;

                        /**
                         * Произвести обработку синхронных задач из очереди.
                         */
                        void ProcessQueue();
                };

                /**
                 * Объект, реализующий функции главного синхропространства. 
                 */
                static Implement* implement;
        };

}

#endif //CNTM_MAINSYNCHROSPACE_H

---