AsyncProcHandleDef.h

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

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

#ifndef CNTM_ASYNCPROCHANDLEDEF_H
#define CNTM_ASYNCPROCHANDLEDEF_H
#include <Cntm/Utils/IntTypes.h>
#include <Cntm/Exceptions/IllegalStateException.h>
#include <Cntm/RefCount/RefPtr.h>
#include <Cntm/Concurrency/ExecutionUnitHandle.h>
#include <Cntm/Synchro/SynchroSpace.h>
#include <Cntm/AsyncProc/BasicAsyncProc.h>

namespace Cntm
{

        namespace SpecUtils { class AsyncProcImpl; }

        class AsyncProc;
        
        /**
         * Хэндл асинхронной процедуры. Наследует класс хэндла единицы выполнения Cntm::ExecutionUnitHandle. Используется для управления асинхронной процедурой.
         * 
         * С одной процедурой может быть связано несколько хэндлов. Класс хэндла поддерживает операции копирования.
         * 
         * Через хэндл обеспечивается получение информации о состоянии выполнения асинхронной процедуры, запуск отсроченной процедуры, ожидание завершения процедуры и установка обработчика завершения.
         * 
         * Данный класс обеспечивает многопоточность.
         * @author Овсеевич Р.
         * \ingroup AsyncProc
         */
        class AsyncProcHandle: public ExecutionUnitHandle, public BasicAsyncProc
        {
        public:
                
                /**
                 * Конструктор по умолчанию. Создает хэндл, не связанный с асинхронной процедурой. 
                 */
                AsyncProcHandle(): ExecutionUnitHandle() {}
                
                /**
                 * Тип асинхронной процедуры: потоковая, отложенная, прямая (см. перечисление Cntm::BasicAsyncProc::ProcType). 
                 */
                ProcType Type() const;
                
                /**
                 * Возвращает значение флага "была ли запущена процедура". Для обычных процедур сразу после создания устанавливается в true, для отсроченных (Suspend...) - после их успешного запуска методом Start(). 
                 */
                bool Started() const;
                
                /**
                 * Возвращает значение флага "завершилась ли процедура". Исходное значение - false. После выхода из асинхронного метода, указанного при создании устанавливается в true. 
                 */
                bool Finished() const;

                /**
                 * Вовзращает флаг успешности завершения асинхронного метода. Если при выполнении асинхронного метода в нем было сгенерировано необработанное исключение, т.е. произошел выход из метода без возврата результата, то флаг содержит false, если произошел нормальный выход из метода оператором return или при достижении конца метода, то данный флаг содержит true. До завершения метода данный флаг содержит false. 
                 */
                bool Success() const;
                
                /**
                 * Произвести запуск отсроченной асинхронной процедуры. Если запуск уже произведен, то ни каких действий не выполняется.
                 * 
                 * Для каждого из типов асинхронных процедур свой метод запуска. Для потоковых - создается новый поток, в котором происходит выполнение указанного асинхронного метода. Для отложенных - производится подготовка синхронизированного вызова указанного метода в указанном синхропространстве. Для прямых - непосредственный вызов указанного метода в методе Start(). Замечание: при прямом вызове все исключения, произошедшие в указанном при создании методе, будут проигнорированы.
                 * 
                 * Исключение: SystemException - системная ошибка при создании нового потока (только для потоковых процедур). 
                 */
                void Start();
                
                /**
                 * Ожидать завершения выполнения асинхронной процедуры. Ожидание может длиться либо бесконечно до завершения, либо указанный интервал времени. В последнем случае возвращается результат ожидания: true - процедура завершилась, false - нет.
                 * 
                 * Предупреждение. Использование ожидания внутри синхропространства д.б. предельно аккуратным, т.к. если, например, начато ожидание внутри синхропространства, а асинхронный метод тоже захочет войти в это же синхропространство, то произойдет взаимоблокировка, приводящая к зависанию.
                 * 
                 * Исключение: SystemException - в случае системной ошибки при ожидании.
                 * @param MSecTimeout - интервал ожидания завершения асинхронной процедуры в мс. Если значение не указано,то ожидание будет длится до завершения процедуры. 
                 */
                bool Wait(uint MSecTimeout = tmInfinite);
                
                /**
                 * Установить обработчик завершения. Обработчик завершения это другая отсроченная асинхронная процедура.
                 * 
                 * Если обработчик был установлен до завершения асинхронной процедуры, то его запуск (методом Start()) будет произведен непосредственно после выхода из асинхронного метода. Если он был установлен позже, то его запуск будет произведен непосредственно из данного метода.
                 * 
                 * У асинхронной процедуры м.б. множество обработчиков завершения, повторные вызовы данного метода не влияют на уже установленные обработчики.
                 * 
                 * Для удобства использования возвращается этот же объект (*this).
                 * 
                 * Исключения:
                 * BadArgException - если обработчик завершения находится в запущенном состоянии.
                 * SystemException - системная ошибка при создании нового потока (только для потоковых процедур).
                 * @param FinishProc - обработчик завершения. Является асинхронной процедурой которая не должна находиться в запущенном состоянии. 
                 */
                AsyncProcHandle& SetFinishProc(const AsyncProcHandle& FinishProc);
                
                /**
                 * Метод аналогичен методу SetFinishProc. Данный метод принимает объект и метод и формирует отсроченную потоковую процедуру на основе указанных данных. В качестве аргумента указывается данный объект, что позволяет обработчику завершения получить результат выполнения. 
                 * 
                 * Сигнатура метода Method должна иметь вид: "void(const AsyncProcHandle& res)".
                 * 
                 * Для удобства использования возвращается этот же объект.
                 * 
                 * См. Cntm::AsyncProc::SuspendThread.
                 * @param Object - объект-обработчик. Задается обычным указателем.
                 * @param Method - метод объекта Object, который будет вызван синхронизированно в указанном синхропространстве.
                 * @param Priority - приоритет потока, опционально, значение по умолчанию - tpNormal (см. перечисление Cntm::BasicAsyncProc::ThreadPriority).
                 * @param HoldRef - хранить ли ссылку на объект Object, если это ссылочный объект. Параметр опциональный, значение по умолчанию - true.
                 */
                template < typename ClassT, typename MethodT >
                AsyncProcHandle& BindFinishToThreadProc(ClassT Object,
                        MethodT Method,
                        ThreadPriority Priority = tpNormal,
                        bool HoldRef = true);

                /**
                 * Метод аналогичен методу SetFinishProc. Данный метод принимает объект и метод и формирует отсроченную отложенную процедуру на основе указанных данных. В качестве аргумента указывается данный объект, что позволяет обработчику завершения получить результат выполнения.
                 * 
                 * Сигнатура метода Method должна иметь вид: "void(const AsyncProcHandle& res)".
                 * 
                 * Для удобства использования возвращается этот же объект.
                 * 
                 * См. Cntm::AsyncProc::SuspendDefer.
                 * @param Object - объект-обработчик. Задается обычным указателем.
                 * @param Method - метод объекта Object, который будет вызван синхронизированно в указанном синхропространстве.
                 * @param Space - синхропространство, в котором будет выполнен метод. Если явно не указано, тоиспользуется синхропространство объекта Object, если это синхрообъект, иначе используется главное синхропространство.
                 * @param HoldRef - хранить ли ссылку на объект Object, если это ссылочный объект. Параметр опциональный, значение по умолчанию - true.
                 */
                template < typename ClassT, typename MethodT >
                AsyncProcHandle& BindFinishToDeferProc(ClassT Object,
                        MethodT Method,
                        SynchroSpace::Ptr Space = SynchroSpace::Ptr(),
                        bool HoldRef = true);

                /**
                 * Метод аналогичен методу SetFinishProc. Данный метод принимает объект и метод и формирует отсроченную прямую процедуру на основе указанных данных. В качестве аргумента указывается данный объект, что позволяет обработчику завершения получить результат выполнения.
                 * 
                 * Сигнатура метода Method должна иметь вид: "void(const AsyncProcHandle& res)".
                 * 
                 * Для удобства использования возвращается этот же объект.
                 * 
                 * См. Cntm::AsyncProc::SuspendDirect.
                 * @param Object - объект-обработчик. Задается обычным указателем.
                 * @param Method - метод объекта Object, который будет вызван синхронизированно в указанном синхропространстве.
                 * @param HoldRef - хранить ли ссылку на объект Object, если это ссылочный объект. Параметр опциональный, значение по умолчанию - true.
                 */
                template < typename ClassT, typename MethodT >
                AsyncProcHandle& BindFinishToDirectProc(ClassT Object,
                        MethodT Method,
                        bool HoldRef = true);

                /**
                 * Изменить значение параметра HoldRef, указанного при создании асинхронной процедуры. Это изменение имеет смысл только если указанный при создании объект - с подсчетом ссылок. Этот параметр влияет на хранение ссылки на объект, чей метод будет выполняться. Если параметр устанвлен в true, то на время выполнения метода ссылка на объект будет сохранена, если в false, то нет.
                 * 
                 * Устанавливать этот параметр в false следует с большой осторожностью, т.к. может привести к уничтожению объекта во время выполнения метода.
                 * @param HoldRef - хранить ли ссылку на объект, указанный при создании процедуры, если это ссылочный объект. 
                 */
                void SetHoldRef(bool HoldRef);
                
        protected:
        
                typedef RefPtr<SpecUtils::AsyncProcImpl> AsyncProcImplPtr;

                
                /**
                 * Конструктор инициализации. 
                 */
                AsyncProcHandle(const AsyncProcImplPtr& Proc);
                
                /**
                 * Метод приведения к ссылочному указателю на объект асинхронной процедуры. 
                 */
                AsyncProcImplPtr Proc() const;
        };

}

#endif //CNTM_ASYNCPROCHANDLEDEF_H

---