QTMainSynchroSpace.h

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

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

#ifdef CNTM_USE_QT_SS

#ifndef CNTM_QTMAINSYNCHROSPACE_H
#define CNTM_QTMAINSYNCHROSPACE_H
#include <qapplication.h>
#include <qevent.h>
#include <qeventloop.h>
#include <boost/thread/recursive_mutex.hpp>
#include <Cntm/Utils/IntTypes.h>
#include <Cntm/Exceptions/IllegalStateException.h>
#include <Cntm/Synchro/SynchroSpace.h>

namespace Cntm
{

        /**
         * Класс главного синхропространства, использующего средства библиотеки QT для реализации функций главного синхропространства.
         * 
         * Для реализации входа/выхода в синхропространство используется мьютекс (критическая секция) библиотеки QT, которая доступна через методы QApplication::lock(), QApplication::tryLock(), QApplication::unlock().
         * 
         * Обработка отложенных синхрозадач производится в цикле обработки сообщений QT, т.е. в процессе выполнения метода QApplication::exec() или при отображении модального окна. Т.о. система гарантирует, что деинициализация синхрообъектов, обработка отложенных событий и т.д. будет выполняться в главном потоке и, соответственно, синхронизирована со всеми остальными событиями библиотеки QT (например с событиями от кнопок, от таймера и т.д.). Замечание: очереди синхрозадач и событий QT - 2 разные очереди, поэтому порядок выполнения отложенных задач и событий QT может нарушаться: задача может быть обработана раньше, чем событие QT, хотя поставлена была позже и наоборот.
         * 
         * С точки зрения режима входа в главное синхропространство QT все события библиотеки выполняются внутри синхропространства в реентерабельном режиме. Это означает, что из обработчиков событий QT, как и из обработчиков отложенных событий можно производить отображение модальных окон. 
         * 
         * Реентерабельный вход в главное синхропространство QT происходит, когда вызывается метод QApplication::exec() или другие методы, приводящие к входу в цикл обработки событий. При попытке реентерабельного входа не из главного потока будет выдано исключение LoopInNoMainThreadException, т.к. библиотека QT запрещает запускать циклы не из главного потока. Если режим входа нереентерабельный, то будет выдано исключение NoReentrantModeException (т.е. в нереентерабельном режиме отображение модальных окон запрещено). Если обработка исключений не поддерживается библиотекой QT, то в этом случае в стандартный поток ошибок будут выданы соответствующие сообщения и программа аварийно завершит работу.
         * 
         * Обеспечение жизненного цикла приложения. Для обеспечения жизненного цикла применяется метод QApplication::exec(). В общем случае жизненный цикл выглядит следующим образом.
         * \code
         * int main(args...)
         * {
         *      Cntm::QTMainSynchroSpace::Prepare();
         *      QApplication a(args...);
         *      Cntm::QTMainSynchroSpace::Begin();
         *      ...
         *      Инициализация
         *      ...
         *      a.exec();
         *      ...
         *      Деинициализация
         *      ...
         *      Cntm::QTMainSynchroSpace::End();
         *      return 0;
         * }
         * \endcode
         * 
         * Верхние три строчки функции main производят создание приложения и подготовку главного синхропространства QT. Далее следует инициализация системы, после чего запускается приложение - это и является жизненным циклом приложения. После завершения работы (например, закрылось главное окно) происходит деинициализация и выход из главного синхропространства - метод End(). Данный метод производит ожидание момента, когда будут уничтожены все синхрообъекты в системе. Для ожидания он использует метод QApplication::exec(). это означает, что во время ожидания цикл обработки сообщений не нарушается.
         * Замечание. В интервале от метода Begin() до входа в цикл обработки событий (a.exec()), от выхода из цикла до входа в следующий цикл, от выхода из цикла до метода End() поток выполнения находится внутри синхропространства в реентерабельном режиме.
         * 
         * Существует более простая и удобная структура приложения:
         * \code
         * int main(args...)
         * {
         *      Cntm::QTMainSynchroSpace::Application a(args...);
         *      ...
         *      Инициализация
         *      ...
         *      a.exec();
         *      ...
         *      Деинициализация
         *      ...
         *      return 0;
         * }
         * \endcode
         * 
         * Если в приложении требуется использовать специальный класс цикла обработки событий, то его следует унаследовать от QTMainSynchroSpace::EventLoop и создать объект цикла до вызова Prepare() или создания объекта QTMainSynchroSpace::Application.
         * 
         * Для более подробной информации см. докементацию по QT (разделы по QApplication и поддержке потоков в QT). От библиотеки QT требуется поддержка многопоточности, поэтому при компиляции следует определить макрос QT_THREAD_SUPPORT в настройках компилятора. При линковке следует использовать библиотеку QT с поддержкой многопоточности.
         * 
         * Для того, что бы использовать QTMainSynchroSpace при компиляции должен быть определен макрос CNTM_USE_QT_SS в настройках компилятора.
         * @author Овсеевич Р.
         * \ingroup Synchro
         */
        class QTMainSynchroSpace: public SynchroSpace
        {
        private:
        
                /**
                 * Класс, обеспечивающий вызов метода Cntm::QTMainsynchroSpace::Prepare() перед созданием объекта класса QApplication.
                 * @author Овсеевич Р. 
                 */
                class PrepareLauncher
                {
                public:
        
                        /**
                         * Конструктор. Обеспечивает вызов Cntm::QTMainsynchroSpace::Prepare().
                         */
                        PrepareLauncher() { QTMainSynchroSpace::Prepare(); }
                };

        public:
                
                typedef RefPtr<QTMainSynchroSpace> Ptr;

                /**
                 * Специальный класс цикла обработки событий QT. Если в приложении используется свой собственный класс цикла, то он должен быть унаследован от данного класса и непосредственно создан программистом перед созданием объекта приложения (см. документацию по QT). Если специальный класс цикла обработки сообщений не используется, то никаких дополнительных действий (создание объекта класса Cntm::QTMainSynchroSpace::EventLoop) выполнять не надо.
                 * @author Овсеевич Р. 
                 */
                class EventLoop: public QEventLoop
                {
                public:

                        /**
                         * Конструктор.
                         */     
                        EventLoop(QObject* parent = 0, const char* name = 0): QEventLoop(parent, name) { created = true; }
                        
                        /**
                         * Статический метод создания объекта класса Cntm::QTMainSynchroSpace::EventLoop. Если объект цикла обработки (в том числе и производный от Cntm::QTMainSynchroSpace::EventLoop) уже создан, то ни каких действий не выполняется.
                         */
                        static void CreateEventLoop() { if (!created) new EventLoop; }
                        
                        /**
                         * Переопределенный метод входа в цикл. Выполняет спец. операции. При перегрузке в потомке необходимо производить его вызов.
                         */
                        int enterLoop();
                        
                protected:
                        
                        /**
                         * Флаг: создан объект или нет.
                         */
                        static bool created;
                };
        
                /**
                 * Класс QT приложения. Наследует класс QApplication. Предназначен для автоматизации вызывов Cntm::QTMainsynchroSpace::Prepare(), Cntm::QTMainsynchroSpace::Begin(), Cntm::QTMainsynchroSpace::End(). Для использования нужно создать объект данного класса вместо объекта класса QApplication.
                 * @author Овсеевич Р.
                 * \ingroup Synchro
                 */
                class Application: private PrepareLauncher, public QApplication
                {
                public:

                        /**
                         * Конструктор. Вызывает соответствующий конструктор класса QApplication. Выполняет операции Cntm::QTMainsynchroSpace::Prepare() и Cntm::QTMainsynchroSpace::Begin().
                         */
                        Application(int& argc, char** argv): PrepareLauncher(), QApplication(argc, argv), ended(false)
                        {
                                QTMainSynchroSpace::Begin();
                        }

                        /**
                         * Конструктор. Вызывает соответствующий конструктор класса QApplication. Выполняет операции Prepare() и Begin().
                         */
                        Application(int& argc, char** argv, bool GUIenabled): PrepareLauncher(),  QApplication(argc, argv, GUIenabled), ended(false)
                        {
                                QTMainSynchroSpace::Begin();
                        }

                        /**
                         * Конструктор. Вызывает соответствующий конструктор класса QApplication. Выполняет операции Cntm::QTMainsynchroSpace::Prepare() и Cntm::QTMainsynchroSpace::Begin().
                         */
                        Application(int& argc, char** argv, Type type): PrepareLauncher(),  QApplication(argc, argv, type), ended(false)
                        {
                                QTMainSynchroSpace::Begin();
                        }

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

        
                /**
                 * Добавить новую задачу в конец очереди. Объект задачи д.б. создан в динамической памяти. После выполнения задача автоматически будет удалена. Класс объекта задачи д.б. унаследован от SynchroSpace::TaskBase.
                 * 
                 * Подробнее о синхрозадачах см. описание класса SynchroSpace и SynchroSpace::TaskBase.
                 * 
                 * Система гарантирует, что задача будет выполнена в контексте главного потока синхронно с прочими событиями библиотеки QT.
                 * 
                 * \throw NullArgException если не указана задача.
                 * @param Task - задача, которую нужно выполнить. Объект задачи д.б. создан в динамической памяти. 
                 */
                void AddSynchroTask(TaskBase* Task) { implement->AddSynchroTask(Task); }
        
                /**
                 * Подготовка главного синхропространства. Должен вызываться до создания объекта QApplication. Если используется специальный цикл обработки событий (унаследованный от QTMainSynchroSpace::EventLoop), то он должен быть создан до вызова данного метода.
                 * 
                 * Вместо вызова этого метода рекомендуется использовать класс QTMainSynchroSpace::Application.
                 * 
                 * \throw IllegalStateException при попытке повторного создания главного синхропространства (главное синхропространство этого же или другого типа уже создано).
                 */
                static void Prepare();
        
                /**
                 * Вход в главное синхропространство (режим входа реентерабельный). Должен вызываться после создания объекта QApplication.
                 * 
                 * Вместо вызова этого метода рекомендуется использовать класс QTMainSynchroSpace::Application.
                 */
                static void Begin() { implement->Start(); }
        
                /**
                 * Выход из главного синхропространства. Метод производит ожидание уничтожения всех синхрообъектов и синхропространств. В процессе ожидания запускается цикл обработки событий. 
                 */
                static void End() { implement->Finish(); }
        
        protected:
                
                friend class Implement;
                
                /**
                 * Деструктор. 
                 */
                ~QTMainSynchroSpace() { implement->MainInstanceDeleted(this); }

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

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

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

        private:
        
                /**
                 * Класс, реализующий все функции синхропространства (вход в синхропространство, выполнение синхронных задач), созданием объекта синхропространства и ожидания его уничтожения.
                 * @author Овсеевич Р. 
                 */
                class Implement: public QObject, public SynchroSpace::IMainSynchroSpaceFactory
                {
                public:
        
                        /**
                         * Конструктор.
                         * 
                         * Исключение: IllegalStateException при попытке повторного создания главного синхропространства.
                         */
                        Implement();
                        
                        /**
                         * Переопределенный метод QObject::event(), который вызывается, когда требуется синхронное выполнение задач или выход когда на главное синхропространство QT не осталось ссылок.
                         */
                        bool event(QEvent* e);
        
                        /**
                         * Реализация метода Cntm::SynchroSpace::IMainSynchroSpaceFactory::QueryMainInstance.
                         */
                        SynchroSpace::Ptr QueryMainInstance();
                        
                        /**
                         * Выполнение захвата критической секции объекта QApplication, которая используется как критическая секция для галавного синхропространства QT.
                         * 
                         * Данный метод для главного потока и так всегда вызывается внутри критической секции, поэтому блокировку можно не выполнять. Это приводит к полному отсутствию рекурсивных блокировок, что, в свою очередь, приводит к тому, что крит. секция не блокируется на длительное время при реентерабельном входе (стандартное поведение QT - обработчик события блокирует крит. секцию, в т.ч. и на время отображения модального окна из обработчика, новое поведение - на время отображения модального окна происходит разблокировка, что позволяет войти в главное синхропространство другим потокам во время отображения модального окна).
                         * 
                         * Вызывается из QTMainSynchroSpace::DoEnter().
                         */
                        void DoEnter() { if (!QTMainSynchroSpace::IsMainThread()) qApp->lock(); }
        
                        /**
                         * Выполнение попытки захвата критической секции объекта QApplication, которая используется как критическая секция для галавного синхропространства QT.
                         * 
                         * Данный метод для главного потока и так всегда вызывается внутри критической секции, поэтому блокировку можно не выполнять. Это приводит к полному отсутствию рекурсивных блокировок, что, в свою очередь, приводит к тому, что крит. секция не блокируется на длительное время при реентерабельном входе (стандартное поведение QT - обработчик события блокирует крит. секцию, в т.ч. и на время отображения модального окна из обработчика, новое поведение - на время отображения модального окна происходит разблокировка, что позволяет войти в главное синхропространство другим потокам во время отображения модального окна).
                         * 
                         * Вызывается из QTMainSynchroSpace::DoTryEnter().
                         */
                        bool DoTryEnter() { return QTMainSynchroSpace::IsMainThread()? true : qApp->tryLock(); }
        
                        /**
                         * Выполнение выхода из критической секции объекта QApplication, которая используется как критическая секция для галавного синхропространства QT.
                         * 
                         * Данный метод для главного потока и так всегда вызывается внутри критической секции, поэтому блокировку можно не выполнять. Это приводит к полному отсутствию рекурсивных блокировок, что, в свою очередь, приводит к тому, что крит. секция не блокируется на длительное время при реентерабельном входе (стандартное поведение QT - обработчик события блокирует крит. секцию, в т.ч. и на время отображения модального окна из обработчика, новое поведение - на время отображения модального окна происходит разблокировка, что позволяет войти в главное синхропространство другим потокам во время отображения модального окна).
                         * 
                         * Вызывается из QTMainSynchroSpace::DoLeave().
                         */
                        void DoLeave() { if (!QTMainSynchroSpace::IsMainThread()) qApp->unlock(); }
        
                        /**
                         * Добавить новую синхронную задачу. Добавляет задачу в очередь и выдает событие самому себе через цикл обработки сообщений приложения QT.
                         * 
                         * Вызывается из QTMainSynchroSpace::AddSynchroTask().
                         * 
                         * Исключение: NullArgException если не указана задача.
                         * @param Task - задача, которую нужно выполнить. Объек задачи д.б. создан в динамической памяти. 
                         */
                        void AddSynchroTask(SynchroSpace::TaskBase* Task)
                        {
                                if (taskQueue.Add(Task)) 
                                        QApplication::postEvent(this, new QEvent(QEvent::Type(QEvent::User + 0)));
                        }
        
                        /**
                         * Действия синхропространства при реентерабельном входе (перед запуском цикла обработки событий QT). Выполняет обработку отложенных задач и выходит из крит. секции QApplication.
                         *
                         * Вызывается из EventLoop::enterLoop() перед входом в цикл обработки событий.
                         * 
                         * Исключения:
                         * LoopInNoMainThreadException при попытке запуска цикла обработки сообщений не из главного потока (в QT такой запуск запрещен).
                         * NoReentrantModeException при попытке запуска цикла обработки событий QT когда вход в главное синхропространство произведен не в REENTRANT режиме.
                         */
                        void ReentrantEnter(int Level);
                        
                        /**
                         * Действия синхропространства при реентерабельном выходе (после запуска цикла обработки событий QT). Входит в крит. секцию QApplication.
                         *
                         * Вызывается из EventLoop::enterLoop() перед входом в цикл обработки событий.
                         */
                        void ReentrantLeave(int Level);
                        
                        /**
                         * Метод запуска. Выполняет вход в крит. секцию QApplication перед началом работы.
                         * 
                         * Вызывается из QTMainSynchroSpace::Begin().
                         */
                        void Start();
                        
                        /**
                         * Метод ожидает уничтожения всех синхрообъектов (последним уничтожается главное синхропространство), выходит из крит. секции QApplication.
                         * 
                         * Вызывается из QTMainSynchroSpace::End().
                         */
                        void Finish();
                        
                        /**
                         * Метод сбрасывает указатель на текущее синхропространство и посылает сообщение о выходе из цикла обработки событий при условии, что оно (Inst) является текущим.
                         * 
                         * Вызывается из QTMainSynchroSpace::~QTMainSynchroSpace().
                         */
                        void MainInstanceDeleted(QTMainSynchroSpace* Inst);
                        
                private:

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


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

}

#endif //CNTM_QTMAINSYNCHROSPACE_H

#endif //CNTM_USE_QT_SS

---