Класс Cntm::RefBaseEx
[Cntm.RefCount]

Граф наследования:Cntm::RefBaseEx:

Полный список членов класса

---

Подробное описание

Более сложная реализация подсчета ссылок.

Применяется в особых случаях, когда возможностей RefBase недостаточно. Кроме функциональности RefBase он обеспечивает расширенные средства по деинициализации объекта при уничтожении ссылок на него. Применяется в качестве базового класса или примеси для пользовательских классов, которые управляются подсчетом ссылок.

Особенности использования класса RefBaseEx в том, что он позволяет использовать ссылочные указатели в деструкторе и производить отложенное уничтожение.

Данный класс содержит виртуальный метод OnReleaseInstance(), который вызывается перед деструктором когда ссылок на объект не осталось и он переходит в удаляемое состояние. Этот метод может использоваться для запуска длительной асинхронной операции деинициализации объекта, например, в другом потоке. Чтобы обрабатывать это событие пользовательские классы должны переопределить этот метод. Реализация метода в RefBaseEx не выполняет ни каких действий.

Выше упоминалось, что при исчезновении ссылок на объект он переводится в удаляемое состояние, в котором подсчет ссылок не работает (см. IRefObject). В отличие от RefBase RefBaseEx позволяет вернуть объект из удаляемого состояние в рабочее, по сути дела начать новый цикл использования объекта. Для этого служит метод ReanimateInstance(). Данному методу передается ссылочный указатель, который инициализируется указателем на данный объект, после завершения метода кол-во ссылок устанавливается в 1 и появляется возможность использовать ссылочные указатели на данный объект. Когда все вновь созданные ссылки на данный будут утеряны, объект вновь перейдет в удаляемое состояние. Второй аргумент данного метода влияет на то, будет ли вызван метод OnReleaseInstance() при повторном переходе в удаляемое состояние (по умолчанию не будет).

Рассмотрим несколько сценариев использования:

1. Использование ссылочных указателей в деструкторе. Для этого в деструкторе следует вызвать ReanimateInstance(), передав ему принимающий указатель, который после завершения метода будет указывать на данный объект. Второй аргумент функции не используется. После этого можно использовать ссылочные указатели на данный объект. Особенности данного сценария:

• когда счетчик ссылок достигнет 0, OnReleaseInstance вызываться не будет;
• после выхода из деструктора пользовательского класса ссылок на объект оставаться не должно. В противном случае для сигнализации о такой ошибке в деструкторе RefBaseEx будет сгенерировано исключение RefObjectUsedException для сигнализации о серьезной ошибке, которое будет автоматически перехвачено библиотекой.

2. Отложенное уничтожение. Для этого следует переопределить метод OnReleaseInstance() и в нем вызвать ReanimateInstance(), передав первым параметром указатель, который будет указывать на данный объект, а вторым - флаг нужно ли вызывать OnReleaseInstance в следующий раз (если ничего не указывать, то вызова не будет). После этого можно передать указатель другим объектам для операций деинициализации или запустить поток, выполняющий эти действия. В последнем случае следует сохранять ссылочный указатель. Это можно обеспечить либо передачей указателя потоку как параметра или использовать поле класса. Перед завершением работы поток должен уничтожить или сбросить указатель в NULL. Особенности данного сценария:

• запрещается вручную удалять объект из метода OnReleaseInstance;
• когда счетчик ссылок повторно достигнет 0, будет опять вызван метод OnReleaseInstance() (если это явно указано при предыдущем вызове). Этот вызов может придти, когда первый OnReleaseInstance еще не завершил работу (например, если полученный указатель будет уничтожен в самом OnReleaseInstance() или фоновый поток закончит работу раньше, чем завершится первый OnReleaseInstance()).
• в случае повторных вызовов OnReleaseInstance() библиотека гарантирует, что деструктор объекта будет вызван после завершения работы всех вызывов OnReleaseInstance, даже если они вложены или выполняются параллельно.

Объекты классов, использующих RefBaseEx, должны размещаться только в динамической памяти, т.к. их поведение сильно связано с подсчетом ссылок, кроме того, принудительное удаление таких объектов запрещено (в деструкторе RefBaseEx будет сгенерировано исключение ForceDeleteRefObjectException, которое будет автоматически перехвачено библиотекой, сигнализирующее о неправильном использовании объекта).

Еще одно назначение класса RefBaseEx - блокировка завершения программы при наличие объектов, унаследованных от RefBaseEx. Более подробное описание этой возможности приведено в документации по методу WaitDestroyAll.

Данный класс обеспечивает многопоточность.

Автор:

Овсеевич Р.

См. определение в файле RefBaseEx.h строка 55

Открытые статические члены
static bool	WaitDestroyAll (uint MSecTimeout=std::numeric_limits< uint >::max())
	Ожидание разрушения всех объектов, унаследованных от RefBaseEx, в течении MSecTimeout мсек.
Защищенные члены
	RefBaseEx ()
	Конструктор.
	~RefBaseEx ()
	Виртуальный деструктор.
template<typename T>
void	ReanimateInstance (RefPtr< T > *Dest, bool RepeatOnRelease=false)
	Перевести объект из удаляемого состояния, в которое он переходит при уничтожении всех ссылок на него, в рабочее.
virtual void	OnReleaseInstance ()
	Данный виртуальный метод вызывается когда объект переходит в удаляемое состояние, если его вызов не был запрещен в предыдущем вызове данного метода с помощью ReanimateInstance.
void	DeleteInstance ()
	Метод обработки события уничтожения последней ссылки на данный объект.

---

Конструктор(ы)

Cntm::RefBaseEx::RefBaseEx

(

)

[inline, protected]

Конструктор.

Производит инициализацию объекта, устанавливает кол-во ссылок в 0.

См. определение в файле RefBaseEx.h строка 76

Cntm::RefBaseEx::~RefBaseEx

(

)

[inline, protected]

Виртуальный деструктор.

Выполняет ряд проверочных действий.

Исключения: RefObjectUsedException - когда на объект еще имеются ссылки. ForceDeleteRefObjectException - когда произошла попытка принудительного удаления объекта. Эти исключения обрабатываются самой библиотекой и служат отладочным целям.

См. определение в файле RefBaseEx.h строка 91

Перекрестные ссылки Cntm::SpecUtils::AtomicVariable::DecAndTest().

---

Методы

static bool Cntm::RefBaseEx::WaitDestroyAll

(

uint

MSecTimeout = std::numeric_limits<uint>::max()

)

[inline, static]

Ожидание разрушения всех объектов, унаследованных от RefBaseEx, в течении MSecTimeout мсек.

Если задержка не указана, то ожидание будет длиться бесконечно.

Результат: true - все объекты уничтожились, false - некоторые объекты остались неуничтоженными.

Функцией можно пользоваться одновременно из нескольких потоков.

См. определение в файле RefBaseEx.h строка 66

template<typename T>

void Cntm::RefBaseEx::ReanimateInstance	(	RefPtr< T > *	Dest,
		bool	RepeatOnRelease = false
	)			[inline, protected]

Перевести объект из удаляемого состояния, в которое он переходит при уничтожении всех ссылок на него, в рабочее.

После вызова этого метода счетчик ссылок устанавливается в 1, становятся вновь доступны ссылочные указатели на данный объект. Если объект не в удаляемом состоянии, то производится установка RepeatOnRelease и возвращается ссылочный указатель.

Данный метод должен вызываться только из переопределенного виртуального метода OnReleaseInstance() или деструктора.

Параметры: Первый параметр этой функции - Dest - адрес ссылочного указателя, который принимает новый указатель на данный объект. Он не должен равняться NULL. Тип Dest является аргументом шаблона (ReanimateInstance - шаблонная функция), поэтому к нему выдвигается такое требование: он должен быть адресом ссылочного указателя на класс данного объекта или класс предка. Второй аргумент - RepeatOnRelease - разрешает или запрещает вызов метода OnReleaseInstance() при следующем переходе объекта в удаляемое состояние. Если он равен false, то будет сразу вызван деструктор, если true, сначала вызовется OnReleaseInstance(). По умолчанию параметр равен false.

Исключения: NullArgException - если первый параметр Dest равен NULL. BadArgException - если тип Dest'а не является типом ссылочного указателя на класс данного объекта или на класс его предка.

См. определение в файле RefBaseEx.h строка 122

Перекрестные ссылки Cntm::SpecUtils::AtomicVariable::Inc().

virtual void Cntm::RefBaseEx::OnReleaseInstance

(

)

[inline, protected, virtual]

Данный виртуальный метод вызывается когда объект переходит в удаляемое состояние, если его вызов не был запрещен в предыдущем вызове данного метода с помощью ReanimateInstance.

Для обработки этого события пользовательский класс может переопределить метод.

Реализация этого метода для RefBaseEx не выполняет ни каких действий.

Все исключения, сгенерированные в переопределнном методе, будут проигнорированы.

См. определение в файле RefBaseEx.h строка 147

void Cntm::RefBaseEx::DeleteInstance

(

)

[protected, virtual]

Метод обработки события уничтожения последней ссылки на данный объект.

Он позволяет либо запустить фоновый процесс уничтожения с длительными действиями, либо уничтожить объект.

Без крайней необходимости этот метод переопределять не рекомендуется.

Переопределяет метод предка Cntm::RefBase.

Переопределяется в Cntm::ActiveRefBaseEx, Cntm::ActiveSynchroRefBaseEx и Cntm::SynchroRefBaseEx.

См. определение в файле RefBaseEx.cpp строка 16

Перекрестные ссылки Cntm::SpecUtils::AtomicVariable::DecAndTest(), Cntm::SpecUtils::AtomicVariable::Inc() и OnReleaseInstance().

---

Объявления и описания членов классов находятся в файлах:

• Cntm/RefCount/RefBaseEx.h
• Cntm/RefCount/RefBaseEx.cpp

---