JANA/Streaming/JTransport.h

0001
0002 // Copyright 2020, Jefferson Science Associates, LLC.
0003 // Subject to the terms in the LICENSE file found in the top-level directory.
0004
0005 #pragma once
0006 #include <JANA/Streaming/JMessage.h>
0007
0008 /// JTransport is a lightweight wrapper for integrating different messaging systems with JANA.
0009
0010 struct JTransport {
0011
0012     enum Result { SUCCESS   /// send/recv succeeded
0013                 , FAILURE   /// Not sure if we want this. Probably throw an exception instead.
0014                 , TRY_AGAIN /// send/recv failed
0015                 , FINISHED  /// Not sure if we want this. End-of-stream happens at a higher level.
0016     };
0017
0018
0019     /// Called exactly once before any calls to send or receive. Use for opening sockets, etc.
0020     /// We don't open sockets in the constructor because JANA expects multiple event sources, which
0021     /// might be constructed immediately but not used until much later, unnecessarily tying up resources.
0022     virtual void initialize() = 0;
0023
0024     /// send should block until the underlying transport has successfully enqueued the message somewhere else.
0025     /// This allows the caller to reuse the same JMessage buffer immediately.
0026     virtual Result send(const JMessage& src_msg) = 0;
0027
0028     /// receive should return as soon as the dest_msg has been written. If there are no messages waiting,
0029     /// receive should return TRY_AGAIN immediately instead of blocking.
0030     virtual Result receive(JMessage& dest_msg) = 0;
0031
0032     /// It is reasonable to close sockets in the destructor, since:
0033     ///  a. The JTransport doesn't have an end-of-stream concept to hook a close() method to
0034     ///  b. The JStreamingEventSource owns the JTransport, so it can destroy it as soon as it is done with it
0035     virtual ~JTransport() = default;
0036 };
0037