yami::core Namespace Reference

Namespace defining the YAMI4-core communication module. More...

Classes
class	agent
	Message broker. More...
class	allocator
	Common interface for the custom memory allocator. More...
class	channel_descriptor
	Descriptor handle for the physical channel. More...
class	locked_allocator
	Locking (thread-safe) wrapper for the block-based allocator. More...
class	non_locked_allocator
	Non-locking (thread-unsafe) block-based allocator. More...
class	parameter_entry
	Read-only view on the parameters entry. More...
class	parameter_iterator
	Iterator to parameter entries. More...
class	parameters
	Collection of message parameters. More...
class	raw_buffer_data_source
	Serializable wrapper for the raw binary data. More...
class	serializable
	Common interface for serializable data source. More...
class	standard_allocator
	Standard (malloc/free), default allocator. More...

Typedefs
typedef void(*	incoming_message_dispatch_function) (void *hint, const char *source, const char *header_buffers[], std::size_t header_buffer_sizes[], std::size_t num_of_header_buffers, const char *body_buffers[], std::size_t body_buffer_sizes[], std::size_t num_of_body_buffers)
typedef void(*	new_incoming_connection_function) (void *hint, const char *source, std::size_t index, std::size_t sequence_number)
typedef void(*	closed_connection_function) (void *hint, const char *name, result reason)
typedef void(*	message_progress_function) (void *hint, std::size_t sent_bytes, std::size_t total_byte_count)
typedef void(*	event_notification_function) (void *hint, event_notification e, const char *str, std::size_t size)
typedef frame_decision(*	frame_acceptor_function) (void *hint, const char *channel_name, int message_id, std::size_t frame_size)
	Type of function callback for frame acceptor facility.
typedef void(*	io_error_function) (void *hint, int error_code, const char *description)
	Type of function callback for internal I/O error logging.
typedef void(*	fatal_error_function) (const char *source_file, int line_number)

Enumerations
enum	result {   ok , no_such_name , bad_type , no_such_index ,   no_memory , nesting_too_deep , not_enough_space , no_entries ,   unexpected_value , bad_protocol , io_error , timed_out ,   channel_closed , bad_state }
	General type for reporting success and error states. More...
enum	event_notification {   agent_closed , listener_added , listener_removed , incoming_connection_open ,   outgoing_connection_open , connection_closed , connection_error , message_sent ,   message_received }
	Type of internal event notification.
enum	frame_decision { accept_this_frame , drop_collected_message_frames }
	Type of frame acceptor decisions.
enum	parameter_type {   unused , boolean , integer , long_long ,   word , long_long_word , double_float , string ,   binary , boolean_array , integer_array , long_long_array ,   word_array , long_long_word_array , double_float_array , string_array ,   binary_array , nested_parameters , nested_parameters_array }
	Type of parameter entry. More...

Functions
DLL void	register_fatal_error_handler (fatal_error_function handler)

Detailed Description

Namespace defining the YAMI4-core communication module.

Typedef Documentation

closed_connection_function

typedef void(* yami::core::closed_connection_function) (void *hint, const char *name, result reason)

Type of function callback (hook) for closing connection.

Parameters

hint	Arbitrary (any) argument provided at the time when the callback was installed.
name	The name of the closing channel.
reason	The reason for closing the connection, this is either channel_closed for regular end-of-stream condition or an appropriate error value that was reported while operating on the given channel.

event_notification_function

typedef void(* yami::core::event_notification_function) (void *hint, event_notification e, const char *str, std::size_t size)

Type of function callback for internal event notifications (logging). Depending on the event type, some callback parameters are used.

fatal_error_function

typedef void(* yami::core::fatal_error_function) (const char *source_file, int line_number)

Type of function callback for reporting internal fatal errors.

Note: This function is supposed to be a customization point for reporting assertion errors; even if this function returns, the code calling it will abort immediately after that. The default handler prints the message on standard error channel.

Parameters

source_file	Name of the source file where the error occured.
line_number	Line number of the place where assertion failed.

incoming_message_dispatch_function

typedef void(* yami::core::incoming_message_dispatch_function) (void *hint, const char *source, const char *header_buffers[], std::size_t header_buffer_sizes[], std::size_t num_of_header_buffers, const char *body_buffers[], std::size_t body_buffer_sizes[], std::size_t num_of_body_buffers)

Type of function callback for incoming message dispatch.

Parameters

hint	Arbitrary (any) argument provided at the time when the callback was installed.
source	Name of the originating channel.
header_buffers	Array of pointers to data buffers that can be used to deserialize the message header.
header_buffer_sizes	Array of sizes of header data buffers.
num_of_header_buffers	Number of elements in the header_buffers and header_buffer_sizes arrays.
body_buffers	Array of pointers to data buffers that can be used to deserialize the message body.
body_buffer_sizes	Array of sizes of body data buffers.
num_of_body_buffers	Number of elements in the body_buffers and body_buffer_sizes arrays.

Note: The arguments to this callback can be directly used with the deserialize function of the parameters class. Note: The callback function is allowed to interact with the same agent except for calling clean() and do_some_work().

message_progress_function

typedef void(* yami::core::message_progress_function) (void *hint, std::size_t sent_bytes, std::size_t total_byte_count)

Type of function callback for outgoing message progress report. If both size values are zero, it means that there was an error while sending the message - the message itself will be abandoned and channel will be closed.

Parameters

hint	Arbitrary (any) argument provided at the time when the callback was installed.
sent_bytes	The number of bytes accumulated from the beginning of the message that have been sent.
total_byte_count	The overall size of the message.

Note: When sent_bytes and total_byte_count are equal it means that the whole message has been sent; if they are both zero it indicates that there was an error and the message was abandoned.

new_incoming_connection_function

typedef void(* yami::core::new_incoming_connection_function) (void *hint, const char *source, std::size_t index, std::size_t sequence_number)

Type of function callback (hook) for new incoming connection. This function sees the new channel already in the proper state and can use it (in particular it can close it).

Parameters

hint	Arbitrary (any) argument provided at the time when the callback was installed.
source	The source (remote) name of the newly created channel.
index	Index for the channel descriptor.
sequence_number	Sequence number for the channel descriptor.

Returns

true if the connection is accepted and false otherwise.

Enumeration Type Documentation

parameter_type

enum yami::core::parameter_type

Type of parameter entry.

Enumerator
unused	Internal mark for unused slots.
boolean	bool
integer	int
long_long	long long
word	unsigned int
long_long_word	unsigned long long
double_float	double
string	string
binary	Binary block.
boolean_array	Array of bool.
integer_array	Array of int.
long_long_array	Array of long long.
word_array	Array of unsigned int.
long_long_word_array	Array of unsigned long long.
double_float_array	Array of double.
string_array	Array of strings.
binary_array	Array of binary blocks.
nested_parameters	Nested parameters object.
nested_parameters_array	Array of nested parameters object.

result

enum yami::core::result

General type for reporting success and error states.

Enumerator
ok	Operation completed successfully.
no_such_name	The given name was not found.
bad_type	The expected type is different than the actual.
no_such_index	Index out of range.
no_memory	Not enough memory.
nesting_too_deep	The nesting of parameters is too deep.
not_enough_space	There is not enough space in the buffer.
no_entries	There are no entries.
unexpected_value	The given value was not recognized.
bad_protocol	The connection protocol is incorrect.
io_error	Unable to perform the I/O operation.
timed_out	The requested operation timed out.
channel_closed	The operation was not possible due to EOF.
bad_state	The given object is in the wrong state.

Function Documentation

register_fatal_error_handler()

DLL void yami::core::register_fatal_error_handler

(

fatal_error_function

handler

)

Registers the custom handler for reporting fatal errors.

Note: this function is not thread-safe and should be called (if at all) before any agent is initialized.