JANA2
C++ framework for multi-threaded data processing
JMessage Struct Referenceabstract

JMessage is an interface for data that can be streamed using JTransports. More...

#include <JMessage.h>

Inheritance diagram for JMessage:
[legend]

Public Member Functions

virtual char * as_buffer ()=0
 Expose the underlying buffer via a raw pointer. More...
 
virtual const char * as_buffer () const =0
 Expose the underlying buffer via a raw pointer. More...
 
virtual size_t get_buffer_capacity () const =0
 Determine the length of the buffer itself, a.k.a. More...
 
virtual size_t get_buffer_size () const
 Determine the length of the buffer's contents, a.k.a. More...
 
virtual bool is_end_of_stream () const =0
 Determine whether this is the last message. More...
 

Detailed Description

JMessage is an interface for data that can be streamed using JTransports.

The basic goal is to have an object wrapper around an old-fashioned char* buffer which can be created automatically on either the stack or the heap. Most importantly, it encapsulates the mess arising from variable message lengths. A common pattern for solving this problem in C is to use flexible array members. Do NOT do this here, as this causes a variety of problems when it comes to type safety and memory safety, and it is not even part of any C++ standard. Instead, agree upon a max message size (which your transport needs anyway), and declare an array of that length. The array length (a.k.a. 'capacity') should be a compile-time constant, and the length of the data contained (a.k.a. 'size') should be tracked in a separate variable.

In addition to the pure virtual methods listed below, conforming implementations need a zero-argument constructor.

Member Function Documentation

◆ as_buffer() [1/2]

virtual const char* JMessage::as_buffer ( ) const
pure virtual

Expose the underlying buffer via a raw pointer.

Returns
A raw pointer to the buffer

◆ as_buffer() [2/2]

virtual char* JMessage::as_buffer ( )
pure virtual

Expose the underlying buffer via a raw pointer.

Returns
A raw pointer to the buffer

◆ get_buffer_capacity()

virtual size_t JMessage::get_buffer_capacity ( ) const
pure virtual

Determine the length of the buffer itself, a.k.a.

the max number of bytes that can be written.

Returns
The number of bytes allocated for the buffer

Referenced by get_buffer_size().

◆ get_buffer_size()

virtual size_t JMessage::get_buffer_size ( ) const
inlinevirtual

Determine the length of the buffer's contents, a.k.a.

the number of bytes which ought to be read

Returns
The number of bytes of meaningful data inside the buffer

References get_buffer_capacity().

◆ is_end_of_stream()

virtual bool JMessage::is_end_of_stream ( ) const
pure virtual

Determine whether this is the last message.

An end-of-stream message is assumed to also contain a meaningful payload. It is not empty like EOF. TODO: Figure out best way to handle empty end-of-stream as well as other control signals such as change-run.

Returns
Whether this is the last message to expect from the producer

The documentation for this struct was generated from the following file: