ExecutionUnitHandle.h

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

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

#ifndef CNTM_EXECUTIONUNITHANDLE_H
#define CNTM_EXECUTIONUNITHANDLE_H
#include <Cntm/Concurrency/Internal/ExecutionUnitImpl.h>

namespace Cntm
{

        /**
         * Класс хэндла единицы выполнения. Является базовым классом для хэндлов асинхронных процедур (класс Cntm::AsyncProcHandle) и потоков активных объектов (класс Cntm::ActiveThreadHandle).
         *
         * Хэндл служит для управления асинхронной процедурой или потоком со стороны создателя единицы выполнения. По сути хэндл является ссылочным указателем на объект единицы выполнения, т.е. пока существует хотя бы один хэндл, связанный с объектом единицы выполнения, этот объект будет существовать.
         *
         * Хэндл может быть связан с единицей выполнения или нет. Это можно определить через свойство Assigned(). Разорвать связь между хэндлом и объектом единицы выполнения можно методом Unassign(). Также связь разрушается, когда происходит уничтожение хэндла. Значения хэндлов могут быть скопированы друг в друга. В этом случае связь со старым объектом разрывается и производится связь с тем объектом, с которым связан источник.
         *
         * Сам по себе объект единицы исполнения не доступен. Все управление этими объектами производится через их хэндлы  (создание асинхронных процедур и потоков активных объектов производится с помощью статических методов классов Cntm::AsyncProc и Cntm::ActiveThread, которые возвращают хэндлы созданных ими объектов единиц выполнения).
         *
         * Данный класс является базовым классом хэндла и предоставляет сервис по установке флага принудительного останова - метод Terminate().
         *
         * Класс поддерживает многопоточность.
         * @author Овсеевич Р.
         * \ingroup Concurrency
         */
        class ExecutionUnitHandle
        {
        public:
                
                /**
                 * Тип идентификатора единицы выполнения. С помощью идентификаторов можно определить, относятся ли хэндлы к одной и той же единице выполнения или нет.
                 *
                 * Тип имеет операторы сравнения, поэтому может использоваться для сортировки. Не имеет конструктора по умолчанию, поэтому при создании переменной этого типа она д.б. явно проинициализирована, например, специальным значением ExecutionUnitHandle::NullId().  
                 * 
                 * Значения идентификаторов могут быть использованы повторно после уничтожения единицы выполнения.
                 */ 
                typedef void* UnitId;
                
                /**
                 * Конструктор по умолчанию. Создает пустой хэндл, не связанный с единицей выполнения. 
                 */
                ExecutionUnitHandle() {}
                
                /**
                 * Конструктор копирования. Дублирует указанный хэндл.
                 * @param Src - дублируемый хэндл. 
                 */
                ExecutionUnitHandle(const ExecutionUnitHandle& Src): impl(Src.impl) {}
                
                /**
                 * Специальное значение идентификатора единицы выполнения, означающее ее отсутствие.
                 */
                static UnitId NullId() { return NULL; }
                
                /**
                 * Оператор присвоения. Уничтожает связь со старым объектом единицы выполнения и устанавливает с новым, взятым из Src.
                 * @param Src - дублируемый хэндл. 
                 */
                ExecutionUnitHandle& operator= (const ExecutionUnitHandle& Src) { impl = Src.impl; return *this; }
                
                /**
                 * Идентификатор текущей единицы выполнения или NullId(), если хэндл не связан с единицей выполнения.
                 */
                UnitId Id() const { return impl.Pointer(); }
                
                /**
                 * Возвращает true, если хэндл связан с единицей выполнения и false - в противном случае. 
                 */
                bool Assigned() const { return (bool)impl; }
                
                /**
                 * Возвращает флаг принудительного останова. Если хэндл не связан с единицей выполнения, то всегда возвращается false. 
                 */
                bool Terminated() const { SpecUtils::ExecutionUnitImpl::Ptr temp = impl; return temp? temp->Terminated() : false; }
                        
                /**
                 * Разорвать связь с единицей выполнения. После этого Assigned() будет возвращать false.
                 * 
                 * Не генерирует исключений. 
                 */
                void Unassign() throw() { impl.SetNull(); }
                
                /**
                 * Установить флаг принудительного завершения. Исходное значение этого флага - false. После вызова этого метода Terminated() и Cntm::ExecutionUnit::Terminated() вернут true, а Cntm::ExecutionUnit::CheckTerminating() сгенерирует исключение (примечание: методы объекта Cntm::ExecutionUnit должны быть вызваны в контексте той исполняемой единицы, с которой связан хэндл).
                 * 
                 * Если хэндл не связан с единицей выполнения, то ни каких действий не выполняется. 
                 * 
                 * Не генерирует исключений.
                 */
                void Terminate() throw() { SpecUtils::ExecutionUnitImpl::Ptr temp = impl; if (temp) temp->Terminate(); }
                
        protected:

                /**
                 * Защищенный конструктор инициализации хэндла. 
                 */
                ExecutionUnitHandle(const SpecUtils::ExecutionUnitImpl::Ptr& Impl): impl(Impl) {}
                
                /**
                 * Ссылочный указатель на объект единицы выполнения. 
                 */
                SpecUtils::ExecutionUnitImpl::Ptr impl;
        };

}

#endif //CNTM_EXECUTIONUNITHANDLE_H

---