transport_shmem.h

/*
 * (c) Copyright, Real-Time Innovations, 2005-2024.
 * All rights reserved.
 *
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */
 
#ifndef transport_shmem_h
#define transport_shmem_h
 
#include "clock/clock_interface.h"
#include "transport/transport_dll.h"
#include "transport/transport_interface.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ================================================================= */
/*               Component: Shared Memory Transport Plugin           */
/* ================================================================= */
 
/*e \dref_ShmemTransportBuiltinGroupDocs
 */
 
/*i \file
 * \ingroup NDDS_Transport_Shmem_Plugin NDDS_TransportBuiltinsComponent
 * \brief Shared-Memory Transport Plugin interface and definitions.
 */
 
/* ================================================================= */
/*                 Shared Memory Properties                          */
/* ================================================================= */
/*e \dref_ShmemTransport_Property_t
 */
struct NDDS_Transport_Shmem_Property_t {
    /*e \dref_ShmemTransport_Property_t_parent
     */
    struct NDDS_Transport_Property_t parent;
 
    /*e \dref_ShmemTransport_Property_t_received_message_count_max
     */
    RTI_INT32 received_message_count_max;
 
    /*e \dref_ShmemTransport_Property_t_receive_buffer_size
     */
    RTI_INT32 receive_buffer_size;
 
    /*e \dref_ShmemTransport_Property_t_enable_udp_debugging
     */
    RTIBool enable_udp_debugging;
 
    /*e \dref_ShmemTransport_Property_t_udp_debugging_address
     */
    NDDS_Transport_Address_t udp_debugging_address;
 
    /*e \dref_ShmemTransport_Property_t_udp_debugging_port
     */
    NDDS_Transport_Port_t udp_debugging_port;
 
    /*i offset used for port -> segment key mapping */
    RTI_INT32 segmentKeyOffset;
 
    /*i factor used for port -> segment key mapping */
    RTI_INT32 segmentKeyFactor;
 
    /*i offset used for port -> semaphore key mapping */
    RTI_INT32 semaphoreKeyOffset;
 
    /*i factor used for port -> semaphore key mapping */
    RTI_INT32 semaphoreKeyFactor;
 
    /*i offset used for port -> mutex key mapping */
    RTI_INT32 mutexKeyOffset;
 
    /*i factor used for port -> mutex key mapping */
    RTI_INT32 mutexKeyFactor;
 
    /*i
     * The maximum duration that a writer can take to write this message.
     * If a writer takes longer, it can be potentially be aborted writing by a
     * reader believing the writer is stuck (i.e. in an infinite loop).
     * The resolution is in milliseconds.
     * Default value is 1000
     */
    RTI_UINT32 maxAllowedWriterDurationMillisec;
 
    /*i
     * IMPORTANT: This value is used for unit testing purposes ONLY!. Possible
     * values are:
     * 1) If this value is
     *    NDDS_TRANSPORT_SHMEM_RESERVED_FORCE_RECV_RESOURCE_FAILURE then create
     *    recv resource will fail
     * 2) If this value is
     *    NDDS_TRANSPORT_SHMEM_RESERVED_USE_TRANSPORT_UUID_AS_SHMEM_UUID
     *    then the shmemUuid will be the same as the transport_uuid.
     */
    RTIBool reserved;
 
    /*i
     * UUID used to check the reachability of a shmem locator received through
     * discovery. After attaching to a shmem segment, we will check that
     * the UUID in the header matches the one in the received locator.
     * If it matches, that means that we are on the same machine than
     * the target locator and that communication is possible through shmem.
     */
    NDDS_Transport_Address_t shmemUUID;
 
    /*i
     * Major version of the shared memory protocol.
     * Different major versions are incompatible.
     */
    RTI_INT16 majorVersion;
};
 
/*i
 * For testing: When reserved is set to this value, create_recv_resource will
 * fail.
 */
#define NDDS_TRANSPORT_SHMEM_RESERVED_FORCE_RECV_RESOURCE_FAILURE 1
 
/*i
 * For testing: When reserved is set to this value,
 * the shmemUuid will be the same as the transport_uuid.
 *
 * This can be used to simulate scenarios where two participants are on
 * different machines even though they run on the same physical machine.
 */
#define NDDS_TRANSPORT_SHMEM_RESERVED_USE_TRANSPORT_UUID_AS_SHMEM_UUID 2
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Shmem plugin class string name
 */
#define NDDS_TRANSPORT_SHMEM_CLASS_NAME "shmem"
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Shmem plugin builtin alias string name
 */
#define NDDS_TRANSPORT_BUILTIN_SHMEM_ALIAS "builtin.shmem"
 
/*e \ingroup  NDDS_Transport_Shmem_Plugin
 * \brief Default value of NDDS_Transport_Property_t#address_bit_count
 */
#define NDDS_TRANSPORT_SHMEM_ADDRESS_BIT_COUNT (-96)
 
/*e @ingroup NDDS_Transport_Shmem_Plugin
 * @brief Default value of NDDS_Transport_Property_t#properties_bitmap.
 */
#define NDDS_TRANSPORT_SHMEM_PROPERTIES_BITMAP_DEFAULT \
  (NDDS_TRANSPORT_PROPERTY_BIT_BUFFER_ALWAYS_LOANED)
 
/*e \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Default value of
 * NDDS_Transport_Property_t#gather_send_buffer_count_max.
 */
#define NDDS_TRANSPORT_SHMEM_GATHER_SEND_BUFFER_COUNT_MAX_DEFAULT (1024)
 
/*e \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Default value of NDDS_Transport_Property_t#message_size_max.
 */
#if defined(RTI_INTY)
  #define NDDS_TRANSPORT_SHMEM_MESSAGE_SIZE_MAX_DEFAULT (9216)
#else
  #define NDDS_TRANSPORT_SHMEM_MESSAGE_SIZE_MAX_DEFAULT (65536)
#endif
 
/*e \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Default value of
 * NDDS_Transport_Shmem_Property_t#received_message_count_max.
 */
#if defined(RTI_INTY)
  #define NDDS_TRANSPORT_SHMEM_RECEIVED_MESSAGE_COUNT_MAX_DEFAULT (8)
#else
  #define NDDS_TRANSPORT_SHMEM_RECEIVED_MESSAGE_COUNT_MAX_DEFAULT (64)
#endif
 
/*e \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Default value of NDDS_Transport_Shmem_Property_t#receive_buffer_size.
 */
#define NDDS_TRANSPORT_SHMEM_RECEIVE_BUFFER_SIZE_DEFAULT \
  (NDDS_TRANSPORT_SHMEM_RECEIVED_MESSAGE_COUNT_MAX_DEFAULT \
   * NDDS_TRANSPORT_SHMEM_MESSAGE_SIZE_MAX_DEFAULT / 4)
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Major version of the shared memory transport containing bug 14240
 * (RTI-28)
 */
#define NDDS_TRANSPORT_SHMEM_MAJOR_BEFORE_BUG_14240_FIX (1)
 
/*e \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Major version for the transport plugin after fixing bug 14240 (RTI-28)
 */
#define NDDS_TRANSPORT_SHMEM_MAJOR_AFTER_BUG_14240_FIX (2)
 
/* SparcSolaris had a shmem version with major 3 */
#define NDDS_TRANSPORT_SHMEM_MAJOR_SPARC_SOLARIS_DEPRECATED (3)
 
/*
 * This is the version of the shared memory transport that uses a concurrent
 * queue with a writer cookie, used in Network Capture (CORE-10280) to get the
 * PID of the source for inbound traffic.
 *
 * There is a parallelism between concurrent queue versions and shared memory
 * versions. We are doing the same here as in
 * REDA_CONCURRENT_QUEUE_VERSION_AFTER_WRITER_COOKIE_SUPPORT: keep the default
 * major version so that there is no interoperability break, but allow (through
 * property configuration) to use a newer one.
 */
#define NDDS_TRANSPORT_SHMEM_MAJOR_AFTER_WRITER_COOKIE_SUPPORT (4)
 
/*
 * This is the version of the shared memory transport that uses a robust
 * pthread mutex to protect the shared memory segment.
 */
#define NDDS_TRANSPORT_SHMEM_MAJOR_AFTER_ROBUST_PTHREAD_MUTEX (5)
 
/* This is the current default major version. */
#define NDDS_TRANSPORT_SHMEM_VERSION_MAJOR_DEFAULT \
  NDDS_TRANSPORT_SHMEM_MAJOR_AFTER_BUG_14240_FIX
 
/*e \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Use this to initialize stack variable.
 * \hideinitializer
 */
#define NDDS_TRANSPORT_SHMEM_PROPERTY_DEFAULT \
    { \
        { \
            NDDS_TRANSPORT_CLASSID_SHMEM, \
            NDDS_TRANSPORT_SHMEM_ADDRESS_BIT_COUNT, \
            NDDS_TRANSPORT_SHMEM_PROPERTIES_BITMAP_DEFAULT, \
            NDDS_TRANSPORT_SHMEM_GATHER_SEND_BUFFER_COUNT_MAX_DEFAULT, \
            NDDS_TRANSPORT_SHMEM_MESSAGE_SIZE_MAX_DEFAULT, \
            NULL, \
            0, /* allow_interfaces_list */ \
            NULL, \
            0, /* deny_interfaces_list */ \
            NULL, \
            0, /* allow_multicast_interfaces_list */ \
            NULL, \
            0,                           /* deny_multicast_interfaces_list */ \
            NDDS_TRANSPORT_UUID_UNKNOWN, /* transport_uuid */ \
            NULL,                        /* domain_participant_ptr */ \
            NULL,                        /* domain_participant_forwarder */ \
            NULL,                        /* thread_name_prefix */ \
            NDDS_TRANSPORT_LENGTH_UNLIMITED, /* max_interface_count */ \
        }, \
                NDDS_TRANSPORT_SHMEM_RECEIVED_MESSAGE_COUNT_MAX_DEFAULT, \
                NDDS_TRANSPORT_SHMEM_RECEIVE_BUFFER_SIZE_DEFAULT, \
                RTI_FALSE, /* enable_udp_debugging */ \
                { \
                    { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 239, 255, 1, 2 } \
                },           /* udp_debugging_address */ \
                7399,        /* udp_debugging_port */ \
                0x400000,    /* 0100 xxxx ... */ \
                1, 0x800000, /* 1000 xxxx ... */ \
                1, 0xB00000, /* 1100 xxxx ... */ \
                1, 1000,     /* maxAllowedWriterDurationMillisec */ \
                RTI_FALSE,   /* reserved */ \
                NDDS_TRANSPORT_ADDRESS_INVALID_INITIALIZER, /* shmemUUID */ \
                NDDS_TRANSPORT_SHMEM_VERSION_MAJOR_DEFAULT  /* majorVersion */ \
    }
 
/* ================================================================= */
/*                 Shared Memory Transport Class                     */
/* ================================================================= */
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Create a new shmem process transport.
 *
 * \copydoc NDDS_Transport_Shmem_new
 *
 * @exception RTI_LOG_MALLOC_FAILURE_d
 * RTI_LOG_CREATION_FAILURE_s RTI_LOG_PRECONDITION_FAILURE
 * RTI_LOG_INIT_FAILURE_s
 */
extern NDDS_Transport_DllExport NDDS_Transport_Plugin *
NDDS_Transport_Shmem_newI(
        const struct NDDS_Transport_Shmem_Property_t *property);
 
/*e \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Create a new shmem process transport.
 *
 * An application may create multiple transports, possibly for use in
 * different domains.
 *
 * @param property_in \st_in Desired behavior of this transport. May be NULL
 * for default property. The transport plugin can only support one unicast
 * receive interface; therefore the interface selection lists are ignored.
 *
 * @return handle to a Shmem inter-process Transport Plugin on success
 * @return NULL on failure.
 */
extern NDDS_Transport_DllExport NDDS_Transport_Plugin *NDDS_Transport_Shmem_new(
        const struct NDDS_Transport_Shmem_Property_t *property_in);
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 */
#define NDDS_Transport_Shmem_new(property_in) \
  NDDS_Transport_Shmem_newI(property_in)
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Realization of NDDS_Transport_Get_Class_Name_Fcn_cEA for Shmem
 * transports.
 *
 * Returns the string "shmem".
 *
 * @see NDDS_Transport_Get_Class_Name_Fcn_cEA for complete
 * documentation.
 */
extern NDDS_Transport_DllExport const char *
NDDS_Transport_Shmem_get_class_name_cEA(NDDS_Transport_Plugin *self);
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Realization of NDDS_Transport_String_To_Address_Fcn_cEA for Shmem
 * transports.
 *
 * There is no natural string representation for an "Shmem"
 * transport address.  Will always return 0.
 *
 * @param address_out \st_out The corresponding numerical value in IPv6
 * format.
 *
 * @param address_in \st_in
 *
 * @see NDDS_Transport_String_To_Address_Fcn_cEA for complete
 * documentation.
 */
extern NDDS_Transport_DllExport RTI_INT32
NDDS_Transport_Shmem_string_to_address_cEA(
        NDDS_Transport_Plugin *self,
        NDDS_Transport_Address_t *address_out,
        const char *address_in);
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Realization of NDDS_Transport_Get_Receive_Interfaces_Fcn_cEA
 * for Shmem transports.
 *
 * @see NDDS_Transport_Get_Receive_Interfaces_Fcn_cEA for complete
 * documentation.
 *
 */
extern NDDS_Transport_DllExport RTI_INT32
NDDS_Transport_Shmem_get_receive_interfaces_cEA(
        NDDS_Transport_Plugin *self,
        RTI_INT32 *found_more_than_provided_for_out,
        RTI_INT32 *interface_reported_count_out,
        NDDS_Transport_Interface_t interface_array_inout[],
        RTI_INT32 interface_array_size_in);
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Returns true if the Shared Memory plugin is usable, false if
 * otherwise.
 *
 * The shared memory plugin may be unusable if a call to create_recv_resource
 * fails to allocate the necessary shared memory segments due to system resource
 * constraints.
 */
extern NDDS_Transport_DllExport RTIBool
NDDS_Transport_Shmem_is_valid(NDDS_Transport_Plugin *self);
 
/*i \ingroup NDDS_Transport_Shmem_Plugin
 * \brief Checks if a shared memory locator is reachable from the current shared
 * memory plugin.
 *
 * @param self \st_out Indicates if the SHMEM segment associated with port_in
 * exists.
 * @param s_reachable_out \st_out RTI_TRUE if the locator is reachable
 * RTI_FALSE otherwise.
 *
 * @param address_in \st_in Input address expected to reach
 *
 * @param port_in \st_in Port in the address
 */
extern NDDS_Transport_DllExport void
NDDS_Transport_Shmem_check_locator_reachability(
        const NDDS_Transport_Plugin *self,
        RTIBool *shmem_segment_exists,
        RTIBool *is_reachable_out,
        const NDDS_Transport_Address_t *address_in,
        NDDS_Transport_Port_t port_in);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* transport_shmem_h */