.. _safety_profile: ############## Safety Profile ############## .. Sect<13> .. _safety_profile--overview: ******** Overview ******** .. Sect<13.1> The Safety Profile configuration allows OpenDDS to be used in environments that have a restricted set of operating system and standard library functions available and that require dynamic memory allocation to occur only at system start-up. OpenDDS Safety Profile (and the corresponding features in ACE) were developed for the `Open Group's FACE specification, edition 2.1 `__. It can be used along with the support for FACE Transport Services to create FACE-conformant DDS applications, or it can be used by general DDS applications that are not written to the FACE Transport Services APIs. This latter use-case is described by this section of the developer's guide. For more information on the former use-case see the file :ghfile:`FACE/README.txt` in the source distribution. .. _safety_profile--safety-profile-subset-of-opendds: ******************************** Safety Profile Subset of OpenDDS ******************************** .. Sect<13.2> The following features of OpenDDS are not available when it is configured for Safety Profile: * DCPSInfoRepo and its associated libraries and tools * Transport types: tcp, udp, multicast, shared memory * The rtps_udp transport type is available (uses UDP unicast or multicast) * OpenDDS Monitor library and monitoring GUI When developing the Safety Profile, the following DDS Compliance Profiles were disabled: * content_subscription * ownership_kind_exclusive * object_model_profile * persistence_profile See :ref:`building--disabling-the-building-of-compliance-profile-features` for more details on compliance profiles. It is possible that enabling any of these compliance profiles in a Safety Profile build will result in a compile-time or run-time error. To build OpenDDS Safety Profile, pass the command line argument ``--safety-profile`` to the configure script along with any other arguments needed for your platform or configuration. When safety profile is enabled in the configure script, the four compliance profiles listed above default to disabled. See :ref:`building` for more information about the configure script. .. _safety_profile--safety-profile-configurations-of-ace: ************************************ Safety Profile Configurations of ACE ************************************ .. Sect<13.3> OpenDDS uses ACE as its platform abstraction library, and in OpenDDS's Safety Profile configuration, one of the following safety profile configurations must be enabled in ACE: * FACE Safety Base (always uses the memory pool) * FACE Safety Extended with Memory Pool * FACE Safety Extended with Standard C++ Dynamic Allocation OpenDDS's configure script will automatically configure ACE. Pass the command line argument ``--safety-profile=base`` to select the Safety Base profile. Otherwise a ``--safety-profile`` (no equals sign) configuration will default to Safety Extended with Memory Pool. The Safety Extended with Standard C++ Dynamic Allocation configuration is not automatically generated by the configure script, but the file ``build/target/ACE_wrappers/ace/config.h`` can be edited after it is generated by configure (and before running make). Remove the macro definition for ``ACE_HAS_ALLOC_HOOKS`` to disable the memory pool. ACE's safety profile configurations have been tested on Linux and on LynxOS-178 version 2.3.2+patches. Other platforms may work too but may require additional configuration. .. _safety_profile--run-time-configurable-options: ***************************** Run-time Configurable Options ***************************** .. Sect<13.4> The memory pool used by OpenDDS can be configured by setting values in the ``[common]`` section of the configuration file. See :cfg:prop:`pool_size` and :cfg:prop:`pool_granularity`. .. _safety_profile--running-ace-and-opendds-tests: ***************************** Running ACE and OpenDDS Tests ***************************** .. Sect<13.5> After configuring and building OpenDDS Safety Profile, note that there are two sub-directories of the top level that each contain some binary artifacts: * ``build/host`` has the build-time code generators tao_idl and opendds_idl * ``build/target`` has the run-time libraries for safety profile ACE and OpenDDS and the OpenDDS tests Therefore, testing needs to be relative to the ``build/target`` sub-directory. Source-in the generated file ``build/target/setenv.sh`` to get all of the needed environment variables. ACE tests are not built by default, but once this environment is set up all it takes to build them is generating makefiles and running make: #. ``cd $ACE_ROOT/tests`` #. ``$ACE_ROOT/bin/mwc.pl -type gnuace`` #. ``make`` Run ACE tests by changing to the ``$ACE_ROOT/tests`` directory and using ``run_test.pl``. Pass any ``-Config XYZ`` options required for your configuration (use ``run_test.pl -h`` to see the available Config options). Run OpenDDS tests by changing to the ``$DDS_ROOT`` and using :ghfile:`tests/auto_run_tests.pl`. Pass ``-Config OPENDDS_SAFETY_PROFILE``, ``-Config SAFETY_BASE`` (if using safety base), ``-Config RTPS``, and ``-Config`` options corresponding to each disabled compliance profile, by default: ``-Config DDS_NO_OBJECT_MODEL_PROFILE -Config DDS_NO_OWNERSHIP_KIND_EXCLUSIVE -Config DDS_NO_PERSISTENCE_PROFILE -Config DDS_NO_CONTENT_SUBSCRIPTION``. Alternatively, an individual test can be run using ``run_test.pl`` from that test's directory. Pass the same set of ``-Config`` options to ``run_test.pl``. .. _safety_profile--using-the-memory-pool-in-applications: ************************************* Using the Memory Pool in Applications ************************************* .. Sect<13.6> When the Memory Pool is enabled at build time, all dynamic allocations made by code in OpenDDS or in ACE (methods invoked by OpenDDS) go through the pool. Since the pool is a general purpose dynamic allocator, it may be desirable for application code to use the pool too. Since these APIs are internal to OpenDDS, they may change in future releases. The class ``OpenDDS::DCPS::MemoryPool`` (:ghfile:`dds/DCPS/MemoryPool.h`) contains the pool implementation. However, most client code shouldn't interact directly with it. The class ``OpenDDS::DCPS::SafetyProfilePool`` (:ghfile:`dds/DCPS/SafetyProfilePool.h`) adapts the pool to the ACE_Allocator interface. ``OpenDDS::DCPS::PoolAllocator`` (:ghfile:`dds/DCPS/PoolAllocator.h`) adapts the pool to the C++ Allocator concept (C++03). Since the ``PoolAllocator`` is stateless, it depends on the ``ACE_Allocator``'s singleton. When OpenDDS is configured with the memory pool, ``ACE_Allocator``'s singleton instance will point to an object of class SafetyProfilePool. Application code that makes use of C++ Standard Library classes can either use ``PoolAllocator`` directly, or make use of the macros defined in :ghfile:`dds/DCPS/PoolAllocator.h` (for example ``String``). Application code that allocates raw (untyped) buffers of dynamic memory can use ``SafetyProfilePool`` either directly or via the ``ACE_Allocator::instance()`` singleton. Application code that allocates objects from the heap can use the ``PoolAllocator`` template. Classes written by the application developer can derive from ``PoolAllocationBase`` (see :ghfile:`dds/DCPS/PoolAllocationBase.h`) to inherit class-scoped operators ``new`` and ``delete``, thus redirecting all dynamic allocation of these classes to the pool.