so_4::api

Пространство имен so_4::api

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

Пространство имен SObjectizer API.

Пространства имен

namespace insend_helper

Вспомогательное пространство имен для реализации запуска insend-событий.

Перечисления

enum insend_dispatching_status_t { insend_dispatching_disabled, insend_dispatching_enabled }

Статус разрешенности обработки insend-событий. Подробнее...

Функции

static void send_coop_dereg_msg (const so_4::rt::impl::coop_map_t::value_type &v)

static void try_destroy_coop (const so_4::rt::impl::coop_map_t::value_type &v)

size_t _check_dereg (size_t &deregistered_coop_count)

Инициировать очередную "сборку мусора".

ret_code_t deregister_coop (const std::string &coop_name)

Дерегистрация кооперации.

void _destroy_coop (so_4::rt::agent_coop_t &coop)

ret_code_t start (so_4::rt::dispatcher_t &disp, so_4::rt::agent_coop_t *initial_coop)

Запуск Run-time.

ret_code_t start (so_4::rt::dispatcher_t *disp, so_4::destroy_disp_flags_t destruction_flag, so_4::rt::agent_coop_t *initial_coop)

Запуск Run-time.

ret_code_t shutdown ()

Подача сигнала на завершение работы системы.

ret_code_t register_coop (so_4::rt::agent_coop_t &coop)

Регистрация кооперации.

ret_code_t make_global_agent (const std::string &agent_name, const std::string &agent_type)

Создание глобального агента.

ret_code_t send_msg (const std::string &agent_name, const std::string &msg_name, void *msg_data=0, const char *receiver=0, unsigned int delay=0, unsigned int period=0)

Отсылка сообщения.

ret_code_t send_msg (const std::string &agent_name, const std::string &msg_name, void *msg_data, const std::string &receiver, unsigned int delay=0, unsigned int period=0)

Отсылка сообщения.

ret_code_t send_msg (const so_4::rt::comm_channel_t &channel_to, const std::string &agent_name, const std::string &msg_name, void *msg_data, const std::string &receiver, unsigned int delay=0, unsigned int period=0)

Отсылка сообщения.

template<class Msg>

so_4::ret_code_t send_msg_safely (const std::string &agent_name, const std::string &msg_name, Msg *msg_data, const std::string &receiver="", unsigned int delay=0, unsigned int period=0)

Безопасная отсылка сообщения.

template<class Msg>

so_4::ret_code_t send_msg_safely (const so_4::rt::comm_channel_t &channel_to, const std::string &agent_name, const std::string &msg_name, Msg *msg_data, const std::string &receiver="", unsigned int delay=0, unsigned int period=0)

Безопасная отсылка сообщения.

void _deliver_msg (const so_4::rt::msg_data_t &data, const insend_dispatching_status_t &insend_status)

Доставка сообщения.

ret_code_t subscribe_event (const std::string &agent, const std::string &event, int priority, const so_4::rt::evt_subscr_t &subscr, const so_4::rt::evt_subscr_t::subscr_flag_t &subscr_flag, const so_4::rt::evt_subscr_t::dispatching_t &dispatching=so_4::rt::evt_subscr_t::normal_dispatching)

Подписка события агента.

ret_code_t query_agent_state (const std::string &agent_name, std::string &state_name)

Определение текущего состояния агента.

static void do_subscription (const so_4::rt::impl::agent_wrapper_ptr_vector_t &wrappers, std::vector< std::string > &names)

static void do_send_messages (const so_4::rt::agent_coop_t &coop, const std::vector< std::string > &agent_names)

static so_4::rt::agent_coop_t * sobjectizer_coop ()

Создание динамической кооперации для агента sobjectizer.

static so_4::rt::agent_coop_t * communicator_coop ()

Создание динамической кооперации для агента communicator.

static ret_code_t check_incidents (so_4::rt::impl::sys_dict_t &dict, const so_4::rt::impl::evt_subscr_impl_t &subscr, so_4::rt::impl::msg_wrapper_ptr_set_t &msgs)

Перечисления

enum so_4::api::insend_dispatching_status_t

Статус разрешенности обработки insend-событий.

Начиная с:
v.4.2.7

Элементы перечислений:

insend_dispatching_disabled Запуск insend-событий запрещен.

insend_dispatching_enabled Немедленный запуск insend-событий разрешен.

Функции

size_t so_4::api::_check_dereg ( size_t & deregistered_coop_count )

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

Возвращает:
количество оставшихся в процессе дерегистрации коопераций.

Внимание:
Это внутреняя функция SObjectizer!

Аргументы:

deregistered_coop_count Приемник числа полностью дерегистрированных коопераций. Данную функцию рекомендуется вызывать до тех пор, пока это значение не будет выставлено в 0.

void so_4::api::_deliver_msg ( const so_4::rt::msg_data_t & data,

const insend_dispatching_status_t & insend_status

)

Доставка сообщения.
Это внутренняя функция для предоставления возможности реализации собственных компонентов для SObjectizer-а (например, диспетчера).
Аргументы:

insend_status Можно ли выполнять insend-диспетчеризацию.

static so_4::rt::agent_coop_t* so_4::api::communicator_coop ( ) [static]

Создание динамической кооперации для агента communicator.

Начиная с:
v.4.2.7

ret_code_t so_4::api::deregister_coop ( const std::string & coop_name )

Дерегистрация кооперации.
Кооперация с указанным именем должна быть зарегистрированной.
Успешное завершение deregister_coop не означает, что кооперация уже изъята из Run-time. Реальное изъятие кооперации произойдет только тогда, когда все агенты кооперации перестанут использоваться (т.е. завершат выполнение всех своих событий; будут выполнены все события, инцидентами которых являются сообщения дерегистрируемых агентов; т.д.).
Примеры:
sample/dyn_reg/main.cpp, sample/filter/c1.cpp, sample/filter/c2.cpp и sample/parent_insend/main.cpp.

ret_code_t so_4::api::make_global_agent ( const std::string & agent_name,

const std::string & agent_type

)

Создание глобального агента.
Эта функция должна вызываться после старта системы. В противном случае невозможно будет подписать коммуникационных агентов на распространение сообщений глобального агента.
Возможно вызывать несколько раз make_global_agent для одного и того же глобального агента при условии, что везде указывается один и тот же тип агента.

Внимание:
Нельзя сделать глобальным агент, уже есть агент с таким же именем, но зарегистрированный как обычный агент. Нельзя зарегистрировать обычного агента, если уже есть глобальный агент с таким же именем.

Заметки:
Глобального агента нельзя изъять из системы.

Аргументы:

agent_name Имя глобального агента.

agent_type Тип глобального агента.

Примеры:
sample/filter/c1.cpp, sample/filter/c2.cpp, sample/filter/server.cpp, sample/high_traffic/client.cpp и sample/high_traffic/server.cpp.

ret_code_t so_4::api::query_agent_state ( const std::string & agent_name,

std::string & state_name

)

Определение текущего состояния агента.
Если агент не имеет состояний, то в state_name возвращается пустая строка.

Заметки:
Возвращается имя состояния, в котором агент находился в момент работы функции query_agent_state. После возврата из query_agent_state агент может находиться в другом состоянии.

Аргументы:

agent_name Имя агента, состояние которого необходимо узнать.

state_name Приемник имени состояния агента.

ret_code_t so_4::api::register_coop ( so_4::rt::agent_coop_t & coop )

Регистрация кооперации.
Имя кооперации должно быть уникальным.
Если coop является экземпляром типа so_4::rt::dyn_agent_coop_t, то после успешной регистрации кооперации объект coop будет уничтожен автоматически при дерегистрации кооперации.
Если coop не является экземпляром типа so_4::rt::dyn_agent_coop_t, то необходимо обеспечить существование объекта coop все время, пока кооперация является зарегистрированной.
Примеры:
sample/parent_insend/main.cpp.

ret_code_t so_4::api::send_msg ( const so_4::rt::comm_channel_t & channel_to,

const std::string & agent_name,

const std::string & msg_name,

void * msg_data,

const std::string & receiver,

unsigned int delay = 0,

unsigned int period = 0

)

Отсылка сообщения.
Отсылка сообщения.
Если period != 0, то инициируется переодическое сообщение. После инициирования переодическое сообщение повторяется до тех пор, пока существует агент-владелец сообщения.
Одно и тоже сообщение может быть инициировано как переодическое несколько раз - каждое сообщение будет возникать независимо от остальных.
Однажды инициированное сообщение нельзя отменить.
Для переодического сообщения delay указывает время, через которое сообщение возникнет в первый раз. Например, если delay == 0, period == 2000, то первый раз сообщение возникнет сразу, а затем будет повторяться каждые 2 секунды. Если delay == 1000, а period == 10000, то первый раз сообщение возникнет через 1 секунду, а затем будет повторяться каждые 10 секунд.

Заметки:
Эта функция должна применяться для поддержки Peer-to-Peer соединений.

Аргументы:

channel_to Коммуникационный канал, в который необходимо отослать сообщение.

ret_code_t so_4::api::send_msg ( const std::string & agent_name,

const std::string & msg_name,

void * msg_data,

const std::string & receiver,

unsigned int delay = 0,

unsigned int period = 0

)

Отсылка сообщения.
Отсылка сообщения.
Если period != 0, то инициируется переодическое сообщение. После инициирования переодическое сообщение повторяется до тех пор, пока существует агент-владелец сообщения.
Одно и тоже сообщение может быть инициировано как переодическое несколько раз - каждое сообщение будет возникать независимо от остальных.
Однажды инициированное сообщение нельзя отменить.
Для переодического сообщения delay указывает время, через которое сообщение возникнет в первый раз. Например, если delay == 0, period == 2000, то первый раз сообщение возникнет сразу, а затем будет повторяться каждые 2 секунды. Если delay == 1000, а period == 10000, то первый раз сообщение возникнет через 1 секунду, а затем будет повторяться каждые 10 секунд.
Аргументы:

receiver Имя агента-получателя сообщения.
Если receiver является пустой строкой, то производится широковещательная рассылка сообщения. Т.е. сообщение получают все подписанные на него агенты.
Если receiver не является пустой строкой, то производится целенаправленная отсылка сообщения. Т.е. сообщение получает только агент с именем receiver.

ret_code_t so_4::api::send_msg ( const std::string & agent_name,

const std::string & msg_name,

void * msg_data = 0,

const char * receiver = 0,

unsigned int delay = 0,

unsigned int period = 0

)

Отсылка сообщения.
Если period != 0, то инициируется переодическое сообщение. После инициирования переодическое сообщение повторяется до тех пор, пока существует агент-владелец сообщения.
Одно и тоже сообщение может быть инициировано как переодическое несколько раз - каждое сообщение будет возникать независимо от остальных.
Однажды инициированное сообщение нельзя отменить.
Для переодического сообщения delay указывает время, через которое сообщение возникнет в первый раз. Например, если delay == 0, period == 2000, то первый раз сообщение возникнет сразу, а затем будет повторяться каждые 2 секунды. Если delay == 1000, а period == 10000, то первый раз сообщение возникнет через 1 секунду, а затем будет повторяться каждые 10 секунд.
Аргументы:

agent_name Агент-владелец сообщения.

msg_name Имя сообщения.

msg_data Данные сообщения.
Если msg_data != 0, то подразумевается, что это динамически созданный объект того типа, который был указан для сообщения в описании класса агента.

receiver Имя агента-получателя сообщения.
Если receiver == 0, то производится широковещательная рассылка сообщения. Т.е. сообщение получают все подписанные на него агенты.
Если receiver != 0, то производится целенаправленная отсылка сообщения. Т.е. сообщение получает только агент с именем receiver.

delay Задержка перед первым появлением сообщения в миллисекундах.
Точность отсчета времени определяется точностью используемой Run-time нити таймера.

period Период повторного появления переодического сообщения.
Точность отсчета времени определяется точностью используемой Run-time нити таймера.

Примеры:
sample/chstate/main.cpp, sample/destroyable_traits/main.cpp, sample/dyn_coop_controlled/main.cpp, sample/dyn_reg/main.cpp, sample/filter/c1.cpp, sample/filter/c2.cpp, sample/filter/server.cpp, sample/hello_all/main.cpp, sample/hello_delay/main.cpp, sample/hello_periodic/main.cpp, sample/hello_world/main.cpp, sample/high_traffic/client.cpp, sample/inheritance/main.cpp, sample/parent_insend/main.cpp, sample/raw_channel/tcp_cln.cpp и sample/subscr_hook/main.cpp.

template<class Msg>

so_4::ret_code_t so_4::api::send_msg_safely ( const so_4::rt::comm_channel_t & channel_to,

const std::string & agent_name,

const std::string & msg_name,

Msg * msg_data,

const std::string & receiver = "",

unsigned int delay = 0,

unsigned int period = 0

) [inline]

Безопасная отсылка сообщения.

Начиная с:
v.4.2.6
Аналог отсылки сообщения через so_4::rt::msg_auto_ptr_t, но реализованный в виде функции. Если отсылка сообщения не удалась, то экземпляр сообщения автоматически уничтожается.
Пример использования:
so_4::api::send_msg_safely( channel_to, so_query_name(), "msg_my", new msg_my( ... ) );
Подробное описание отсылки сообщений см. so_4::api::send_msg().
Аргументы:

channel_to Коммуникационный канал, в который необходимо отослать сообщение.

agent_name Агент владелец сообщения.

msg_name Имя отсылаемого сообщения.

msg_data Данные сообщения. Указатель на динамически созданный объект, который будет уничтожен либо в результате успешной доставки сообщения, либо из-за невозможности отсылки сообщения.

receiver Получатель сообщения

delay Задержка перед диспетчеризацией сообщения.

template<class Msg>

so_4::ret_code_t so_4::api::send_msg_safely ( const std::string & agent_name,

const std::string & msg_name,

Msg * msg_data,

const std::string & receiver = "",

unsigned int delay = 0,

unsigned int period = 0

) [inline]

Безопасная отсылка сообщения.

Начиная с:
v.4.2.6
Аналог отсылки сообщения через so_4::rt::msg_auto_ptr_t, но реализованный в виде функции. Если отсылка сообщения не удалась, то экземпляр сообщения автоматически уничтожается.
Пример использования:
so_4::api::send_msg_safely( so_query_name(), "msg_my", new msg_my( ... ) );
Подробное описание отсылки сообщений см. so_4::api::send_msg().
Аргументы:

agent_name Агент владелец сообщения.

msg_name Имя отсылаемого сообщения.

msg_data Данные сообщения. Указатель на динамически созданный объект, который будет уничтожен либо в результате успешной доставки сообщения, либо из-за невозможности отсылки сообщения.

receiver Получатель сообщения

delay Задержка перед диспетчеризацией сообщения.

Примеры:
sample/hello_all/main.cpp, sample/hello_periodic/main.cpp, sample/high_traffic/client.cpp, sample/high_traffic/server.cpp, sample/parent_insend/main.cpp и sample/raw_channel/tcp_cln.cpp.

ret_code_t so_4::api::shutdown ( )

Подача сигнала на завершение работы системы.
Если Run-time запущен, то вызов shutdown даст сигнал Run-time завершить работу.
Работа будет остановлена без учета состояния зарегистрированых в системе агентов. Поэтому, обращение к shutdown должно рассматриваться как экстренное завершение работы системы.
Примеры:
sample/raw_channel/tcp_cln.cpp.

static so_4::rt::agent_coop_t* so_4::api::sobjectizer_coop ( ) [static]

Создание динамической кооперации для агента sobjectizer.

Начиная с:
v.4.2.7

ret_code_t so_4::api::start ( so_4::rt::dispatcher_t * disp,

so_4::destroy_disp_flags_t destruction_flag,

so_4::rt::agent_coop_t * initial_coop

)

Запуск Run-time.

Начиная с:
v.4.2.6
Если Run-time успешно запущен, то возврат из этой функции осуществляется только после завершения работы Run-time.
Если so_4::auto_destroy_disp == destruction_flag, то перед возвратом из данной функции диспетчер будет автоматически уничтожен. Даже, если запуск SObjectizer Run-Time не удался.
Аргументы:

disp Диспетчер, который должен применяться для работы Run-time SObjectizer. Должен быть указателем на динамичесткий объект, если so_4::auto_destroy_disp == destruction_flag.

destruction_flag Признак необходимости уничтожения диспетчера перед возвратом из функции.

initial_coop Стартовая кооперация, которая должна быть зарегистрирована сразу после запуска Run-time.
Если содержит 0, значит нет стартовой кооперации.
Если не 0, и регистрация завершается неудачно, то Run-time останавливается и функция start возвращает код ошибки.

ret_code_t so_4::api::start ( so_4::rt::dispatcher_t & disp,

so_4::rt::agent_coop_t * initial_coop

)

Запуск Run-time.
Если Run-time успешно запущен, то возврат из этой функции осуществляется только после завершения работы Run-time.
Аргументы:

disp Диспетчер, который должен применяться для работы Run-time SObjectizer

initial_coop Стартовая кооперация, которая должна быть зарегистрирована сразу после запуска Run-time.
Если содержит 0, значит нет стартовой кооперации.
Если не 0, и регистрация завершается неудачно, то Run-time останавливается и функция start возвращает код ошибки.

Примеры:
sample/chstate/main.cpp, sample/destroyable_traits/main.cpp, sample/dyn_coop_controlled/main.cpp, sample/dyn_reg/main.cpp, sample/filter/c1.cpp, sample/filter/c2.cpp, sample/filter/server.cpp, sample/hello_all/main.cpp, sample/hello_delay/main.cpp, sample/hello_periodic/main.cpp, sample/hello_world/main.cpp, sample/high_traffic/client.cpp, sample/high_traffic/server.cpp, sample/inheritance/main.cpp, sample/parent_insend/main.cpp, sample/raw_channel/tcp_cln.cpp, sample/raw_channel/tcp_srv.cpp и sample/subscr_hook/main.cpp.

ret_code_t so_4::api::subscribe_event ( const std::string & agent,

const std::string & event,

int priority,

const so_4::rt::evt_subscr_t & subscr,

const so_4::rt::evt_subscr_t::subscr_flag_t & subscr_flag,

const so_4::rt::evt_subscr_t::dispatching_t & dispatching = so_4::rt::evt_subscr_t::normal_dispatching

)

Подписка события агента.
Приоритет события изменяется в любом случае. Для того, чтобы изменить только приоритет события необходимо указать флаг so_4::rt::evt_subscr_t::e_no_change.
Аргументы:

agent Имя агента, событие которого будет подписано

event Имя подписываемого события.

priority Приоритет события.

subscr Инциденты события.

subscr_flag Что нужно делать с инцидентами (полная замена, частичное изъятие, добавление, оставить без изменений).

dispatching Тип диспетчеризации события.

Документация по SObjectizer. Последние изменения: Thu Jan 12 10:52:50 2006. Создано системой

1.4.6-NO


Пространства имен
namespace	insend_helper
	Вспомогательное пространство имен для реализации запуска insend-событий.
Перечисления
enum	insend_dispatching_status_t { insend_dispatching_disabled, insend_dispatching_enabled }
	Статус разрешенности обработки insend-событий. Подробнее...
Функции
static void	send_coop_dereg_msg (const so_4::rt::impl::coop_map_t::value_type &v)
static void	try_destroy_coop (const so_4::rt::impl::coop_map_t::value_type &v)
size_t	_check_dereg (size_t &deregistered_coop_count)
	Инициировать очередную "сборку мусора".
ret_code_t	deregister_coop (const std::string &coop_name)
	Дерегистрация кооперации.
void	_destroy_coop (so_4::rt::agent_coop_t &coop)
ret_code_t	start (so_4::rt::dispatcher_t &disp, so_4::rt::agent_coop_t *initial_coop)
	Запуск Run-time.
ret_code_t	start (so_4::rt::dispatcher_t disp, so_4::destroy_disp_flags_t destruction_flag, so_4::rt::agent_coop_t initial_coop)
	Запуск Run-time.
ret_code_t	shutdown ()
	Подача сигнала на завершение работы системы.
ret_code_t	register_coop (so_4::rt::agent_coop_t &coop)
	Регистрация кооперации.
ret_code_t	make_global_agent (const std::string &agent_name, const std::string &agent_type)
	Создание глобального агента.
ret_code_t	send_msg (const std::string &agent_name, const std::string &msg_name, void msg_data=0, const char receiver=0, unsigned int delay=0, unsigned int period=0)
	Отсылка сообщения.
ret_code_t	send_msg (const std::string &agent_name, const std::string &msg_name, void *msg_data, const std::string &receiver, unsigned int delay=0, unsigned int period=0)
	Отсылка сообщения.
ret_code_t	send_msg (const so_4::rt::comm_channel_t &channel_to, const std::string &agent_name, const std::string &msg_name, void *msg_data, const std::string &receiver, unsigned int delay=0, unsigned int period=0)
	Отсылка сообщения.
template<class Msg>
so_4::ret_code_t	send_msg_safely (const std::string &agent_name, const std::string &msg_name, Msg *msg_data, const std::string &receiver="", unsigned int delay=0, unsigned int period=0)
	Безопасная отсылка сообщения.
template<class Msg>
so_4::ret_code_t	send_msg_safely (const so_4::rt::comm_channel_t &channel_to, const std::string &agent_name, const std::string &msg_name, Msg *msg_data, const std::string &receiver="", unsigned int delay=0, unsigned int period=0)
	Безопасная отсылка сообщения.
void	_deliver_msg (const so_4::rt::msg_data_t &data, const insend_dispatching_status_t &insend_status)
	Доставка сообщения.
ret_code_t	subscribe_event (const std::string &agent, const std::string &event, int priority, const so_4::rt::evt_subscr_t &subscr, const so_4::rt::evt_subscr_t::subscr_flag_t &subscr_flag, const so_4::rt::evt_subscr_t::dispatching_t &dispatching=so_4::rt::evt_subscr_t::normal_dispatching)
	Подписка события агента.
ret_code_t	query_agent_state (const std::string &agent_name, std::string &state_name)
	Определение текущего состояния агента.
static void	do_subscription (const so_4::rt::impl::agent_wrapper_ptr_vector_t &wrappers, std::vector< std::string > &names)
static void	do_send_messages (const so_4::rt::agent_coop_t &coop, const std::vector< std::string > &agent_names)
static so_4::rt::agent_coop_t *	sobjectizer_coop ()
	Создание динамической кооперации для агента sobjectizer.
static so_4::rt::agent_coop_t *	communicator_coop ()
	Создание динамической кооперации для агента communicator.
static ret_code_t	check_incidents (so_4::rt::impl::sys_dict_t &dict, const so_4::rt::impl::evt_subscr_impl_t &subscr, so_4::rt::impl::msg_wrapper_ptr_set_t &msgs)