dtlmod::Stream

class Stream

A class that implements the Stream abstraction in the DTL. A Stream defines the connection between the applications that produce or consume data and the DTL.

A Stream acts as a factory of Engine objects which are in charge of moving or storing data according to a specified Transport method. Opening a Stream creates and returns a handler on an Engine.

A Stream also acts as a factory of Variable objects. It keep records of the definition of the Variable objects to be injected into or retrieve from this Stream.

Public Types

enum class Mode

An enum that defines the access mode for a Stream.

Values:

enumerator Publish

Publish. To inject data into the DTL.

enumerator Subscribe

Subscribe. To retrieve data from the DTL.

Public Functions

std::shared_ptr<Variable> define_variable(const std::string &name, const std::vector<size_t> &shape, const std::vector<size_t> &start, const std::vector<size_t> &count, size_t element_size)

Define a Variable for this Stream.

This function creates a new Variable and the corresponding entry in the internal directory of the Stream that stores all the known variables. This definition does not refer to the data carried by the Variable but provides information about its shape (here a multi-dimensional array) and element type.

Parameters:

• name – The name of the new variable.

• shape – A vector that specifies the total number of element in each dimension.

• start – A vector that specifies the offset at which the calling Actor start to own data in each dimension.

• count – A vector that specifies how many elements the calling Actor owns in each dimension.

• element_size – The size of the elements in the Variable.

Returns:

A shared pointer on the newly created Variable

std::shared_ptr<Variable> define_variable(const std::string &name, size_t element_size)

Define a scalar Variable for this Stream.

This function creates a new scalar Variable and the corresponding entry in the internal directory of the Stream that stores all the known variables. This definition does not refer to the data carried by the Variable but provides information about its shape (here a scalar) and element type.

Parameters:

• name – The name of the new Variable.

• element_size – The size of the elements in the Variable.

Returns:

A shared pointer on the newly created Variable.

inline const char *get_cname() const

Helper function to print out the name of the Stream.

Returns:

The corresponding C-string

const char *get_engine_type_str() const

Helper function to print out the Engine::Type of the Stream.

Returns:

The corresponding C-string

inline const std::string &get_name() const

Helper function to print out the name of the Stream.

Returns:

The corresponding string

inline unsigned int get_num_publishers() const

Helper function to obtain the number of actors connected to Stream in Mode::Publish.

Returns:

The number of publishers for that Stream.

inline unsigned int get_num_subscribers() const

Helper function to obtain the number of actors connected to Stream in Mode::Subscribe.

Returns:

The number of subscribers for that Stream.

const char *get_transport_method_str() const

Helper function to print out the Transport::Method of the Stream.

Returns:

The corresponding C-string

std::shared_ptr<Variable> inquire_variable(const std::string &name) const

Retrieve a Variable information by name.

Parameters:

name – The name of desired Variable.

Returns:

Either a shared pointer on the Variable object if known, nullptr otherwise.

std::shared_ptr<Engine> open(const std::string &name, Mode mode)

Open a Stream and create an Engine.

When multiple actors open the same Stream, only the first one to call this function is in charge of creating an Engine object for that Stream. The Engine creation is thus in a critical section. Each actor calling the open() function is considered as a subscriber to the created Engine.

Both Engine::Type and Transport::Method have to be specified before opening a Stream.

For the FileEngine engine type, name corresponds to a fullpath to where to write data. This fullpath is structured as follows: netzone_name:file_system_name:/path/to/file_name.

Parameters:

• name – name of the Engine created when opening the Stream.

• mode – either Stream::Mode::Publish or Stream::Mode::Subscribe.

Returns:

A shared pointer on the corresponding Engine.

bool remove_variable(const std::string &name)

Remove a Variable of the list of variables known by the Stream.

Parameters:

name – The name of the variable to remove.

Returns:

A boolean indicating if the Variable has been successfully removed or not.

Stream *set_engine_type(const Engine::Type &engine_type)

Helper function to print out the access Mode of the Stream.

Stream configuration function: set the Engine type to create.

Parameters:

engine_type – The type of Engine to create when opening the Stream.

Returns:

The corresponding C-string

Returns:

The calling Stream (enable method chaining).

Stream *set_rendez_vous()

Stream configuration function: use a rendez-vous mode.

Setting the rendez-vous mode for a Stream imposes that publishers must wait for at least one Subscriber to open that Stream to completer their own open.

Returns:

The calling Stream (enable method chaining).

Stream *set_transport_method(const Transport::Method &transport_method)

Stream configuration function: set the Transport Method to use.

Parameters:

transport_method – the Transport methode to use when opening the Stream.

Returns:

The calling Stream (enable method chaining).