blob_transport.hpp

Go to the documentation of this file.

/* Flow-IPC: Core
 * Copyright 2023 Akamai Technologies, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in
 * compliance with the License.  You may obtain a copy
 * of the License at
 *
 *   https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in
 * writing, software distributed under the License is
 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 * CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing
 * permissions and limitations under the License. */
 
/// @file
 
// Not compiled: for documentation only.  Contains concept docs as of this writing.
#ifndef IPC_DOXYGEN_ONLY
static_assert(false, "As of this writing this is a documentation-only \"header\" "
                       "(the \"source\" is for humans and Doxygen only).");
#else // ifdef IPC_DOXYGEN_ONLY
 
namespace ipc::transport
{
 
// Types.
 
/**
 * A documentation-only *concept* defining the behavior of an object capable of reliably/in-order *sending* of
 * discrete messages, each containing a binary blob.  This is paired with
 * the Blob_receiver concept which defines reception of such messages.
 *
 * The concept is exactly identical to Native_handle_sender except that in the latter each message consists
 * of 0-1 native handles and 0-1 binary blobs; whereas here it is always exactly 1 of the latter.  More precisely,
 * each message contains 1 binary blob, whose length must be at least 1 byte.  You may interpret notes in common-sense
 * fashion; for example send_blob_max_size() here corresponds to `send_meta_blob_max_size()` there.
 *
 * Therefore we keep the documentation very light, only pointing out the differences against Native_handle_sender --
 * which are summarized in the preceding paragraph.  All other notes from Native_handle_sender apply here.
 *
 * @see Native_handle_sender, an identical concept with 1 feature (native handle transmission) added.
 */
class Blob_sender
{
public:
  // Constants.
 
  /// Shared_name relative-folder fragment (no separators) identifying this resource type.  Equals `_receiver`'s.
  static const Shared_name S_RESOURCE_TYPE_ID;
 
  // Types.
 
  /**
   * Return type, typically a `struct`, for blob_send_stats().
   *
   * In addition: the impl must choose one of the following paths.  Note that stat::Blob_snd_stats defines statistics
   * relevant to any concept impl of Blob_sender.
   *   -# This type *is* stat::Blob_snd_stats.  Therefore, given a value `S` of this type, you can count on this:
   *      `using ipc::transport::stat::blob_snd_stats; assert(&(blob_snd_stats(S)) == &S)`.
   *      - That is: your impl adds no stats beyond the concept-level ones.
   *   -# This type *is not* stat::Blob_snd_stats but contains one via some type of composition.  Therefore your
   *      Blob_sender impl must be accompanied (in the same namespace, for ADL) with a
   *      free function such that this works:
   *      `using ipc::transport::stat::blob_snd_stats; const stat::Blob_snd_stats& core_stats = blob_snd_stats(S)`.
   *      - That is: your impl adds some stats on top of the concept-level ones.
   */
  using Blob_snd_stats = value;
 
  // Constructors/destructor.
 
  /**
   * Default ctor: Creates a peer object in NULL (neither connected nor connecting) state.
   *
   * All notes from Native_handle_sender() default ctor doc header apply.
   */
  Blob_sender();
 
  /**
   * `sync_io`-core-adopting ctor: Creates a peer object in PEER state by subsuming a `sync_io` core in that state.
   *
   * @param sync_io_core_in_peer_state_moved
   *        See Native_handle_sender concept.
   */
  Blob_sender(sync_io::Blob_sender&& sync_io_core_in_peer_state_moved);
 
  /**
   * Move-constructs from `src`; `src` becomes as-if default-cted (therefore in NULL state).
   *
   * @param src
   *        Source object.  For reasonable uses of `src` after this ctor returns: see default ctor doc header.
   */
  Blob_sender(Blob_sender&& src);
 
  /// Disallow copying.
  Blob_sender(const Blob_sender&) = delete;
 
  /**
   * Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state, and if it
   * is still active) and cancels any pending completion handlers by invoking them ASAP with
   * error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER.
   *
   * All notes from ~Native_handle_sender() doc header apply.
   */
  ~Blob_sender();
 
  // Methods.
 
  /**
   * Move-assigns from `src`; `*this` acts as if destructed; `src` becomes as-if default-cted (therefore in NULL state).
   * No-op if `&src == this`.
   *
   * @see ~Blob_sender().
   *
   * @param src
   *        Source object.  For reasonable uses of `src` after this ctor returns: see default ctor doc header.
   * @return `*this`.
   */
  Blob_sender& operator=(Blob_sender&& src);
 
  /// Disallow copying.
  Blob_sender& operator=(const Blob_sender&) = delete;
 
  /**
   * In PEER state: Returns max `blob.size()` such that send_blob() shall not fail due to too-long
   * payload with error::Code::S_INVALID_ARGUMENT.  Always the same value once in PEER state.  The opposing
   * Blob_receiver::receive_blob_max_size() shall return the same value (in the opposing object potentially
   * in a different process).
   *
   * If `*this` is not in PEER state (in particular if it is default-cted or moved-from), returns zero; else
   * a positive value.
   *
   * @return See above.
   */
  size_t send_blob_max_size() const;
 
  /**
   * In PEER state: Synchronously, non-blockingly sends one discrete message, reliably and in-order, to the opposing
   * peer; the message consists of the provided binary blob (of length at least 1 byte).  Providing a null blob
   * results in undefined behavior (assertion may trip).
   *
   * All notes from Native_handle_sender::send_native_handle() doc header apply.
   *
   * @param blob
   *        A binary blob to send; behavior undefined unless `blob.size() >= 1`.
   * @param err_code
   *        See above.
   * @return See above.
   */
  bool send_blob(const util::Blob_const& blob, Error_code* err_code = nullptr);
 
  /**
   * Equivalent to send_blob() but sends a graceful-close message instead of the usual payload; the opposing
   * peer's Blob_receiver shall receive it reliably and in-order via Blob_receiver::async_receive_blob() in the form of
   * #Error_code = error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE.
   *
   * All notes from Native_handle_sender::async_end_sending() doc header apply.
   *
   * @tparam Task_err
   *         See above.
   * @param on_done_func
   *        See above.
   * @return See above.
   */
  template<typename Task_err>
  bool async_end_sending(Task_err&& on_done_func);
 
  /**
   * Equivalent to `async_end_sending(F)` wherein `F()` does nothing.
   *
   * All notes from Native_handle_sender::end_sending() doc header apply.
   *
   * @return See above.
   */
  bool end_sending();
 
  /**
   * In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level messages that
   * are ignored except that they reset any idle timer as enabled via Blob_receiver::idle_timer_run()
   * (or similar).
   *
   * All notes from Native_handle_sender::auto_ping() doc header apply.
   *
   * @param period
   *        See above.
   * @return See above.
   */
  bool auto_ping(util::Fine_duration period = default_value);
 
  /**
   * Returns the accumulated transport statistics as of this call.
   * If not in PEER state returns a zeroed-out stats object.
   *
   * @see #Blob_snd_stats doc header about how to obtain a transport::stat::Blob_snd_stats core
   *      from the returned `struct`.
   *
   * Thread-safe: can be called concurrently with any other method including `send_*()`.
   * The returned copy is a consistent snapshot.
   *
   * @return Stats snapshot by value.
   */
  Blob_snd_stats blob_send_stats() const;
 
  /**
   * Resets the transport statistics as of this call.  The formal meaning of a reset is discussed in
   * `flow::util::stat` doc header.  If not in PEER state this is a no-op.
   *
   * Thread-safe: can be called concurrently with any other method including `send_*()`.
   */
  void blob_send_stats_reset();
}; // class Blob_sender
 
/**
 * A documentation-only *concept* defining the behavior of an object capable of reliably/in-order *receiving* of
 * discrete messages, each containing a binary blob.  This is paired with
 * the Blob_sender concept which defines sending of such messages.
 *
 * The concept is exactly identical to Native_handle_receiver except that in the latter each message consists
 * of 0-1 native handles and 0-1 binary blobs; whereas here it is always exactly 1 of the latter.  More precisely,
 * each message contains 1 binary blob, whose length must be at least 1 byte.  You may interpret notes in common-sense
 * fashion; for example receive_blob_max_size() here corresponds to `receive_meta_blob_max_size()` there.
 *
 * Therefore we keep the documentation very light, only pointing out the differences against Native_handle_receiver --
 * which are summarized in the preceding paragraph.  All other notes from Native_handle_receiver apply here.
 *
 * @see Native_handle_receiver, an identical concept with 1 feature (native handle transmission) added.
 */
class Blob_receiver
{
public:
  // Constants.
 
  /// Shared_name relative-folder fragment (no separators) identifying this resource type.  Equals `_sender`'s.
  static const Shared_name S_RESOURCE_TYPE_ID;
 
  /**
   * If `false` then `blob.size() < receive_blob_max_size()` in PEER-state async_receive_blob()
   * or `batch->target_payload_size() < receive_blob_max_size()` in PEER-state async_receive_blob_batch()
   * shall yield non-pipe-hosing error::Code::INVALID_ARGUMENT, and it shall never yield
   * pipe-hosing error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE; else the latter may occur, while the former
   * shall never occur for that reason.
   *
   * @see "Blob underflow semantics" in Native_handle_receiver concept doc header; they apply equally here.
   */
  static constexpr bool S_BLOB_UNDERFLOW_ALLOWED = value;
 
  /// All notes from Native_handle_receiver::S_RCV_NATIVE_HANDLE_BATCH_SZ_RECOMMENDATION doc header apply.
  static constexpr size_t S_RCV_BLOB_BATCH_SZ_RECOMMENDATION = value;
 
  // Types.
 
  /// See `async_receive_*_batch()` argument `batch`.
  template<typename Msg_resource>
  using Blob_batch_in = Msg_batch_in<Msg_resource, true>;
 
  /**
   * Return type, typically a `struct`, for blob_receive_stats().
   *
   * In addition: the impl must choose one of the following paths.  Note that stat::Blob_rcv_stats defines statistics
   * relevant to any concept impl of Blob_receiver.
   *   -# This type *is* stat::Blob_rcv_stats.  Therefore, given a value `S` of this type, you can count on this:
   *      `using ipc::transport::stat::blob_rcv_stats; assert(&(blob_rcv_stats(S)) == &S)`.
   *      - That is: your impl adds no stats beyond the concept-level ones.
   *   -# This type *is not* stat::Blob_rcv_stats but contains one via some type of composition.  Therefore your
   *      Blob_receiver impl must be accompanied (in the same namespace, for ADL) with a
   *      free function such that this works:
   *      `using ipc::transport::stat::blob_rcv_stats; const stat::Blob_rcv_stats& core_stats = blob_rcv_stats(S)`.
   *      - That is: your impl adds some stats on top of the concept-level ones.
   */
  using Blob_rcv_stats = value;
 
  // Constructors/destructor.
 
  /**
   * Default ctor: Creates a peer object in NULL (neither connected nor connecting) state.
   *
   * All notes from Native_handle_receiver() default ctor doc header apply.
   */
  Blob_receiver();
 
  /**
   * `sync_io`-core-adopting ctor: Creates a peer object in PEER state by subsuming a `sync_io` core in that state.
   *
   * @param sync_io_core_in_peer_state_moved
   *        See Native_handle_sender concept.
   */
  Blob_receiver(sync_io::Blob_receiver&& sync_io_core_in_peer_state_moved);
 
  /**
   * Move-constructs from `src`; `src` becomes as-if default-cted (therefore in NULL state).
   *
   * @param src
   *        Source object.  For reasonable uses of `src` after this ctor returns: see default ctor doc header.
   */
  Blob_receiver(Blob_receiver&& src);
 
  /// Disallow copying.
  Blob_receiver(const Blob_receiver&) = delete;
 
  /**
   * Destroys this peer endpoint which will end the conceptual incoming-direction pipe (in PEER state, and if it
   * is still active) and cancels any pending completion handlers by invoking them ASAP with
   * error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER.
   *
   * All notes from ~Native_handle_receiver() doc header apply.
   */
  ~Blob_receiver();
 
  // Methods.
 
  /**
   * Move-assigns from `src`; `*this` acts as if destructed; `src` becomes as-if default-cted (therefore in NULL state).
   * No-op if `&src == this`.
   *
   * @see ~Blob_receiver().
   *
   * @param src
   *        Source object.  For reasonable uses of `src` after this ctor returns: see default ctor doc header.
   * @return `*this`.
   */
  Blob_receiver& operator=(Blob_receiver&& src);
 
  /// Disallow copying.
  Blob_receiver& operator=(const Blob_receiver&) = delete;
 
  /**
   * In PEER state: Returns min target-blob size such that (1) async_receive_blob() shall not fail
   * with error::Code::S_INVALID_ARGUMENT (only if #S_BLOB_UNDERFLOW_ALLOWED is `false`; otherwise not relevant),
   * and (2) async_receive_blob_batch() shall not similarly fail,
   * and (3) neither shall *ever* fail with error::Code::S_MESSAGE_SIZE_EXCEEDS_USER_STORAGE.  Please see
   * "Blob underflow semantics" (for Native_handle_receiver, but applied in common-sense fashion to us) for
   * explanation of these semantics.
   *
   * Always the same value once in PEER state.  The opposing
   * Blob_sender::send_blob_max_size() shall return the same value (in the opposing object potentially
   * in a different process).
   *
   * If `*this` is not in PEER state (in particular if it is default-cted or moved-from), returns zero; else
   * a positive value.
   *
   * @return See above.
   */
  size_t receive_blob_max_size() const;
 
  /**
   * In PEER state: Asynchronously awaits one discrete message -- as sent by the opposing peer via
   * Blob_sender::send_blob() or `"Blob_sender::*end_sending()"` -- and
   * receives it into the given target locations, reliably and in-order.
   *
   * All notes from Native_handle_receiver::async_receive_native_handle() doc header apply.  In particular
   * watch out for the semantics regarding `target_blob.size()` and potential resulting errors.
   *
   * Additionally, a corollary to counterpart concept Blob_sender requirements: this method shall never yield
   * `size_t n_rcvd = 0` to `on_done_func()`, as it is not allowed to send an empty message (blob).
   * (Native_handle_sender is allowed to do so, but only if such an empty meta-blob is paired with
   * a non-null `Native_handle`.)
   *
   * ### Informal suggestion w/r/t a `Native_handle_sender` that is also a `Blob_sender` ###
   * Suppose you have class `X` (e.g., Native_socket_stream is such a class) that implements *both*
   * concepts.  Suppose an `X` is on the opposing side of a `*this`.  Then we informally recommend that
   * this async_receive_blob() detect the situation wherein the opposing `X`:
   *   - used `send_native_handle(hndl, blob, ...)` or equivalent; and
   *   - that method or equivalent sent no `hndl` (e.g., the above method was passed `hndl` that contained
   *     no handle: `hndl.null() == true`).
   *
   * It should emit an error in that case.  Flow-IPC itself uses error::Code::S_BLOB_RECEIVER_GOT_NON_BLOB.
   *
   * This is technically not a formal requirement.  It's just nice, as it detects a user misbehavior as opposed
   * to an internal impl bug.
   *
   * @tparam Task_err_sz
   *         See above.
   * @param target_blob
   *        `target_blob.data()...` shall be written to by the time `on_done_func()` is executed with a falsy
   *        code, bytes numbering `N`, where `N` is passed to that callback.  `N` shall not exceed
   *        `target_blob.size()`.  See above.
   * @param on_done_func
   *        See above.
   * @return See above.
   */
  template<typename Task_err_sz>
  bool async_receive_blob(const util::Blob_mutable& target_blob, Task_err_sz&& on_done_func);
 
  /**
   * In PEER state: Asynchronously awaits 1+ discrete message(s) -- as sent by the opposing peer via
   * Blob_sender::send_blob() or `"Blob_sender::*end_sending()"` -- and
   * receives them into the target locations as described by `*batch` slots, reliably and in-order.
   *
   * All notes from Native_handle_receiver::async_receive_native_handle_batch() doc header apply.
   *
   * Additionally, a corollary to counterpart concept Blob_sender requirements: this method shall never yield
   * a slot (index `idx`) such that `batch->result_payload_blob(idx) == 0`; meaning an empty blob was received.
   * That is because it is not allowed to send an empty message (blob).
   * (Native_handle_sender is allowed to do so, but only if such an empty meta-blob is paired with
   * a non-null `Native_handle`.)
   *
   * @tparam Msg_resource
   *         See above.
   * @tparam Task_err
   *         See above.
   * @param batch
   *        See above.  However note that Blob_batch_in<Msg_resource>::result_payload_hndl() (the would-be method
   *        itself) shall not exist, as `Blob_batch_in<M>` is `Msg_batch_in<M, true>`; note the `NO_HNDLS = true`.
   * @param assume_would_block
   *        See above.
   * @param on_done_func
   *        See above.
   * @return Same notes as for async_receive_blob().
   */
  template<typename Msg_resource, typename Task_err>
  bool async_receive_blob_batch(Blob_batch_in<Msg_resource>* batch, bool assume_would_block, Task_err&& on_done_func);
 
  /**
   * In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is, once at least
   * the specified time has passed since the last received low-level traffic (or this call, whichever most
   * recently occurred), to emit the pipe-hosing error error::Code::S_RECEIVER_IDLE_TIMEOUT.
   *
   * All notes from Native_handle_receiver::idle_timer_run() doc header apply.
   *
   * @param timeout
   *        See above.
   * @return See above.
   */
  bool idle_timer_run(util::Fine_duration timeout = default_value);
 
  /**
   * Returns the accumulated transport statistics as of this call.
   * If not in PEER state returns a zeroed-out stats object.
   *
   * @see #Blob_rcv_stats doc header about how to obtain a transport::stat::Blob_rcv_stats core
   *      from the returned `struct`.
   *
   * Thread-safe: can be called concurrently with any other method including `async_receive_*()`.
   * The returned copy is a consistent snapshot.
   *
   * @return Stats snapshot by value.
   */
  Blob_rcv_stats blob_receive_stats() const;
 
  /**
   * Resets the transport statistics as of this call.  The formal meaning of a reset is discussed in
   * `flow::util::stat` doc header.  If not in PEER state this is a no-op.
   *
   * Thread-safe: can be called concurrently with any other method including `async_receive_*()`.
   */
  void blob_receive_stats_reset();
}; // class Blob_receiver
 
} // namespace ipc::transport
 
#endif // ifdef IPC_DOXYGEN_ONLY