Remove explicit segment requesting ability from subscribers and separate runtime mapping request from initialization

Author: Graham Palmer

doc/design/draft/named-segments.md

@@ -57,8 +57,29 @@ have the proper access rights.
 
 ### Optional additional requirements
 
-* When initializing the runtime, a list of segment names may be provided. In this case, rather than mapping all shared memory segments available in the system, only those that are named shall be mapped.
-  * When a communication endpoint requests a segment that has not been mapped, this may be configured to either result in a failure or in mapping the requested segment on the fly.
+* When initializing the runtime, the user may specify via an enum whether they wish to map
+  * All segments to which the current process has read access
+  * All segments to which the current process has write access
+  * All segments to which the current process has either read or write access
+  * No segments (Default)
+* The user may additionally map specific segments after initialization by calling
+  * `mapSegmentForReading(name)`
+    * This will check for existence of the specified segment and map it as long as user has read access to it
+    * An informative error will be returned under the following circumstances
+      * The segment has already been mapped
+      * The segment does not exist
+      * The segment exists but the current process does not have read access to it
+  * `mapSegmentForWriting(name)`
+    * This will check for the existence of the specified segment and map it as long as the user has write access to it
+    * An informative error will be returned under the following circumstances
+      * The segment has already been mapped
+      * The segment does not exist
+      * The segment exists but the current process does not have write access to it
+* When the user attempts to create a publisher that requests a segment which is not mapped, this will trigger the error handler and cause program termination.
+  * In the future if expose a builder-pattern method of creating publishers, we could instead have the builder return an error indicating the segment is not mapped.
+  * An alternative to the above is to add an additional enum with configuration options allowing for the runtime to map requested segments on the fly. This increases flexibility, however because it is already possible to tell the runtime to map a specific segment would not add much value. A user who wishes to ensure a publisher's segment is already mapped may simply call `mapSegmentForWriting(name)`, ignoring the error indicating that the segment has already been mapped.
+* When a subscriber is created, an error will only occur if **no** segment has been mapped. Otherwise if a publisher on the same channel as the subscriber publishes to a segment the subscriber does not have access to (whether because the segment is unmapped or because the subscriber does not have read access), this will result in a fatal error. 
+  * Improvements could be made to the RouDi logic determining if publishers and subscribers are compatible - to check if the subscriber has access to the segment in which the publisher publishes. This is however considered out of scope for the current design proposal.
 
 ## Design
 
@@ -93,38 +114,21 @@ struct PublisherOptions
   ShmName_t segmentName{""};
 ```
 
-#### When creating a Subscriber
-
-A similar field will be added to the [SubscriberOptions struct](../../../iceoryx_posh/include/iceoryx_posh/popo/subscriber_options.hpp), except that it will support multiple elements
-
-```
-struct SubscriberOptions
-{
-  ...
-  vector<ShmName_t, MAX_SUBSCRIBER_SEGMENTS> segmentNames{};
-```
-
-`MAX_SUBSCRIBER_SEGMENTS` can be set to some reasonably small value to start with since explicitly allowing many but not all read-access segments is an unlikely use case. 
-
-If this assumption turns out to be wrong however, we can always update it to be `MAX_SHM_SEGMENTS` instead.
-
 #### When creating Clients and Servers
 
-Clients and Servers will have similar fields, distinguished by request/response:
+Clients and Servers will have similar fields as publishers for the messages which they produce:
 
 ```
 struct ClientOptions
 {
   ...
   ShmName_t requestSegmentName{""};
-  vector<ShmName_t, MAX_RESPONSE_SEGMENTS> responseSegmentNames{};
 ```
 
 ```
 struct ServerOptions
 {
   ...
-  vector<ShmName_t, MAX_REQUEST_SEGMENTS> requestSegmentNames{};
   ShmName_t responseSegmentName{""};
 ```
 
@@ -141,17 +145,20 @@ Tying this together with requesting segments, this could look something like:
 class DefaultRuntimeBuilder
 {
   ...
-  IOX_BUILDER_PARAMETER(vector<ShmName_t>, shmSegmentNames, {});
-  IOX_BUILDER_PARAMETER(bool, allowUnmappedSegments, false);
+  IOX_BUILDER_PARAMETER(MappedSegments, premappedSegments, MappedSegments::ReadAndWrite)
+  IOX_BUILDER_PARAMETER(vector<ShmName_t, MAX_SHM_SEGMENTS>, shmSegmentNames, {});
+  IOX_BUILDER_PARAMETER(UnmappedSegmentBehavior, unmappedSegmentBehavior, UnmappedSegmentBehavior::LoadOnDemand);
   ...
   public:
     expected<DefaultRuntime, RuntimeBuilderError> create() noexcept;
 ```
 
-The `create` method of this builder would then return a custom error if a 
-segment was requested that either does not exist or the current process does not have access to.
+The `create` method of this builder would then return a custom error if:
+  * A segment is requested which does not exist
+  * A segment is requested which the current process does not have access to
+  * A segment is requested which has already been captured by the `premappedSegments` option
 
-Additionally, when a publisher or subscriber is created, the `allowUnmappedSegments` would determine whether or not we fail or try to map the newly requested segment on the fly.
+Additionally, when a publisheris created, the `unamppedSegmentBehavior` option would determine whether or not we fail or try to map the newly requested segment on the fly.
 
 ### Segment Matching Algorithm
 
@@ -177,39 +184,27 @@ In RouDi, given:
     4. At the end of iteration, if a matching segment has been found, return the segment information
     5. Otherwise return an error indicating that no matching segment has been found
 
-#### Endpoints requesting read access (Subscriber, Client Response, Server Request)
-
-In RouDi, when handling a port request for a new subscriber (and WLOG for clients and servers), given:
-* PublisherOptions for a single publisher publishing on the requested topic
-* SubscriberOptions for the requested subscriber
-
-We determine if the endpoints are compatible as follows (and we repeat this for each publisher if there are several):
-1. To determine if the subscriber and publisher segments match:
-    1. If the list of segment names provided by the subscriber is non-empty, check if any name matches the name provided by the publisher (an empty name is a non-match)
-    2. If the list of segment names provided by the subscriber is empty, then it is always a match
-2. Determine if blocking policies are compatible
-3. Determine if history request is compatible
-4. Return true if all cases are met
-
-If no publisher is compatible with a subscriber, then RouDi will refuse to provide a port, as is the current behavior when subscribers have incompatible blocking policies.
-
 #### Runtime requesting segments to map
 
 In the client process, while initializing the runtime, given:
 * `userGroups` - A list of POSIX user groups a publishing process belongs to called 
-* `segmentContainer` - A list of shared memory segment information 
+* `segmentContainer` - A list of shared memory segment information
+* `premappedSegments` - An enum indicating which group of segments should be mapped by default
 * `segmentFilter` - A (possibly empty) list of segment names to filter against
 
 In order to determine which segments to map:
 
-1. If `segmentFilter` is empty then
-    1. Determine which segments the process has access rights (read or write) to.
-    2. Map all of them.
+1. Map segments according to the `premappedSegments` option
+  1. If read access segments are requested, map every segment the user has read access to, but not write access
+  2. If write access segments are requested, map every segment the user has write access to
+  3. If read and write access segmeents are requested, map every segment the user has either read or write access to
+  4. If no segments are requested, do nothing
 2. If `segmentFilter` is not empty
     1. Iterate over each name in the filter
     2. If there is a segment that matches the name in the filter
-        1. If the process has access rights to that segment, map it
-        2. If not, return an error indicating that a segment was requested the runtime does not have access to.
+        1. If the segment has already been mapped, return an error indicating that a segment has been requested twice. The error should contain access permissions and the value of the `premappedSegments` option the user understands why it has already been mapped.
+        2. Otherwise, if the process has access rights to that segment, map it
+        2. If the process does not have access rights, return an error indicating that a segment was requested the runtime does not have access to.
     3. If there is no segment that matches the name in the filter, return an error indicating that there is no segment matching the one requested to be mapped.
 
 ## Development Roadmap