From c8e234ec72a3c0a2d3bffab5170782f0ff09bbc1 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Thu, 14 Apr 2022 17:37:14 -0700 Subject: [PATCH 1/9] Add 'best available' QoS policies The best available policy should select the highest level of service for the QoS setting while matching with the majority of endpoints. For example, in the case of a DDS middleware subscription, this means: - Prefer reliable reliability if all existing publishers on the same topic are reliable, otherwise use best effort. - Prefer transient local durability if all existing publishers on the same topic are transient local, otherwise use volatile. - Prefer manual by topic liveliness if all existing publishers on the same topic are manual by topic, otherwise use automatic. - Use a deadline that is equal to the largest deadline of existing publishers on the same topic. - Use a liveliness lease duration that is equal to the largest lease duration of existing publishers on the same topic. Signed-off-by: Jacob Perron --- rmw/include/rmw/qos_profiles.h | 14 ++++++++++++++ rmw/include/rmw/types.h | 17 ++++++++++++++++- rmw/src/qos_string_conversions.c | 15 +++++++++++++++ rmw/test/test_qos_string_conversions.cpp | 3 +++ 4 files changed, 48 insertions(+), 1 deletion(-) diff --git a/rmw/include/rmw/qos_profiles.h b/rmw/include/rmw/qos_profiles.h index 89b30e97..1cf81df0 100644 --- a/rmw/include/rmw/qos_profiles.h +++ b/rmw/include/rmw/qos_profiles.h @@ -100,6 +100,20 @@ static const rmw_qos_profile_t rmw_qos_profile_system_default = false }; +/// Match majority of endpoints currently available while maintaining the highest level of service +static const rmw_qos_profile_t rmw_qos_profile_best_available = +{ + RMW_QOS_POLICY_HISTORY_KEEP_LAST, + 10, + RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE, + RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE, + RMW_QOS_DEADLINE_BEST_AVAILABLE, + RMW_QOS_LIFESPAN_DEFAULT, + RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE, + RMW_QOS_LIVELINESS_LEASE_DURATION_BEST_AVAILABLE, + false +}; + static const rmw_qos_profile_t rmw_qos_profile_unknown = { RMW_QOS_POLICY_HISTORY_UNKNOWN, diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index 2dd31534..becb2e8d 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -381,6 +381,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_reliability_policy_e /// Attempt to deliver samples, but some may be lost if the network is not robust RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT, + /// Will match the majority of endpoints and use a reliable policy if possible + RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE, + /// Reliability policy has not yet been set RMW_QOS_POLICY_RELIABILITY_UNKNOWN } rmw_qos_reliability_policy_t; @@ -413,6 +416,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e /// Samples are not persistent RMW_QOS_POLICY_DURABILITY_VOLATILE, + /// Will match the majority of endpoints and use a transient local policy if possible + RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE, + /// Durability policy has not yet been set RMW_QOS_POLICY_DURABILITY_UNKNOWN } rmw_qos_durability_policy_t; @@ -452,18 +458,27 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e // Using `3` for backwards compatibility. RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC = 3, + /// Will match the majority of endpoints and use a manual by topic policy if possible + RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 4, + /// Liveliness policy has not yet been set - RMW_QOS_POLICY_LIVELINESS_UNKNOWN = 4 + RMW_QOS_POLICY_LIVELINESS_UNKNOWN = 5 } rmw_qos_liveliness_policy_t; /// QoS Deadline default. #define RMW_QOS_DEADLINE_DEFAULT RMW_DURATION_UNSPECIFIED +/// Will match the majority of endpoints while maintaining as strict a policy as possible +/// Value is RMW_DURATION_INFINITE - 1 +#define RMW_QOS_DEADLINE_BEST_AVAILABLE {9223372036LL, 854775806LL} /// QoS Lifespan default. #define RMW_QOS_LIFESPAN_DEFAULT RMW_DURATION_UNSPECIFIED /// QoS Liveliness lease duration default. #define RMW_QOS_LIVELINESS_LEASE_DURATION_DEFAULT RMW_DURATION_UNSPECIFIED +/// Will match the majority of endpoints while maintaining as strict a policy as possible +/// Value is RMW_DURATION_INFINITE - 1 +#define RMW_QOS_LIVELINESS_LEASE_DURATION_BEST_AVAILABLE {9223372036LL, 854775806LL} /// ROS MiddleWare quality of service profile. typedef struct RMW_PUBLIC_TYPE rmw_qos_profile_s diff --git a/rmw/src/qos_string_conversions.c b/rmw/src/qos_string_conversions.c index 98265786..d5783280 100644 --- a/rmw/src/qos_string_conversions.c +++ b/rmw/src/qos_string_conversions.c @@ -53,6 +53,8 @@ rmw_qos_durability_policy_to_str(enum rmw_qos_durability_policy_e value) return "transient_local"; case RMW_QOS_POLICY_DURABILITY_VOLATILE: return "volatile"; + case RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE: + return "best_available"; case RMW_QOS_POLICY_DURABILITY_UNKNOWN: // fallthrough default: return NULL; @@ -85,6 +87,8 @@ rmw_qos_liveliness_policy_to_str(enum rmw_qos_liveliness_policy_e value) return "automatic"; case RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC: return "manual_by_topic"; + case RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE: + return "best_available"; case RMW_QOS_POLICY_LIVELINESS_UNKNOWN: // fallthrough default: return NULL; @@ -101,6 +105,8 @@ rmw_qos_reliability_policy_to_str(enum rmw_qos_reliability_policy_e value) return "reliable"; case RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT: return "best_effort"; + case RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE: + return "best_available"; case RMW_QOS_POLICY_RELIABILITY_UNKNOWN: // fallthrough default: return NULL; @@ -157,6 +163,9 @@ rmw_qos_durability_policy_from_str(const char * str) if (RMW_QOS_STREQ_WITH_LITERAL("volatile", str)) { return RMW_QOS_POLICY_DURABILITY_VOLATILE; } + if (RMW_QOS_STREQ_WITH_LITERAL("best_available", str)) { + return RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE; + } return RMW_QOS_POLICY_DURABILITY_UNKNOWN; } @@ -189,6 +198,9 @@ rmw_qos_liveliness_policy_from_str(const char * str) if (RMW_QOS_STREQ_WITH_LITERAL("manual_by_topic", str)) { return RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC; } + if (RMW_QOS_STREQ_WITH_LITERAL("best_available", str)) { + return RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE; + } return RMW_QOS_POLICY_LIVELINESS_UNKNOWN; } @@ -205,5 +217,8 @@ rmw_qos_reliability_policy_from_str(const char * str) if (RMW_QOS_STREQ_WITH_LITERAL("best_effort", str)) { return RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT; } + if (RMW_QOS_STREQ_WITH_LITERAL("best_available", str)) { + return RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE; + } return RMW_QOS_POLICY_RELIABILITY_UNKNOWN; } diff --git a/rmw/test/test_qos_string_conversions.cpp b/rmw/test/test_qos_string_conversions.cpp index 126ad399..922001c6 100644 --- a/rmw/test/test_qos_string_conversions.cpp +++ b/rmw/test/test_qos_string_conversions.cpp @@ -41,15 +41,18 @@ TEST(test_qos_policy_stringify, test_policy_values) { TEST_QOS_POLICY_VALUE_STRINGIFY(durability, RMW_QOS_POLICY_DURABILITY_SYSTEM_DEFAULT); TEST_QOS_POLICY_VALUE_STRINGIFY(durability, RMW_QOS_POLICY_DURABILITY_TRANSIENT_LOCAL); TEST_QOS_POLICY_VALUE_STRINGIFY(durability, RMW_QOS_POLICY_DURABILITY_VOLATILE); + TEST_QOS_POLICY_VALUE_STRINGIFY(durability, RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE); TEST_QOS_POLICY_VALUE_STRINGIFY(history, RMW_QOS_POLICY_HISTORY_KEEP_LAST); TEST_QOS_POLICY_VALUE_STRINGIFY(history, RMW_QOS_POLICY_HISTORY_KEEP_ALL); TEST_QOS_POLICY_VALUE_STRINGIFY(history, RMW_QOS_POLICY_HISTORY_SYSTEM_DEFAULT); TEST_QOS_POLICY_VALUE_STRINGIFY(liveliness, RMW_QOS_POLICY_LIVELINESS_AUTOMATIC); TEST_QOS_POLICY_VALUE_STRINGIFY(liveliness, RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC); TEST_QOS_POLICY_VALUE_STRINGIFY(liveliness, RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT); + TEST_QOS_POLICY_VALUE_STRINGIFY(liveliness, RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE); TEST_QOS_POLICY_VALUE_STRINGIFY(reliability, RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT); TEST_QOS_POLICY_VALUE_STRINGIFY(reliability, RMW_QOS_POLICY_RELIABILITY_RELIABLE); TEST_QOS_POLICY_VALUE_STRINGIFY(reliability, RMW_QOS_POLICY_RELIABILITY_SYSTEM_DEFAULT); + TEST_QOS_POLICY_VALUE_STRINGIFY(reliability, RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE); TEST_QOS_POLICY_STRINGIFY_CORNER_CASES(durability, DURABILITY); TEST_QOS_POLICY_STRINGIFY_CORNER_CASES(history, HISTORY); From f6d235776de66a3ff1b9388ed5021fa0c1eb2288 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Tue, 19 Apr 2022 14:08:27 -0700 Subject: [PATCH 2/9] Improve documentation Signed-off-by: Jacob Perron --- rmw/include/rmw/types.h | 60 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 2 deletions(-) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index becb2e8d..8644fac9 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -382,6 +382,16 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_reliability_policy_e RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT, /// Will match the majority of endpoints and use a reliable policy if possible + /** + * A policy will be chosen at the time of creating a subscription or publisher. + * A reliable policy will by chosen if it matches with all discovered endpoints, + * otherwise a best effort policy will be chosen. + * + * The middleware is not expected to update the policy after creating a subscription or + * publisher, even if the chosen policy is incompatible with newly discovered endpoints. + * Therefore, this policy should be used with care since non-deterministic behavior + * can occur due to races with discovery. + */ RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE, /// Reliability policy has not yet been set @@ -417,6 +427,16 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e RMW_QOS_POLICY_DURABILITY_VOLATILE, /// Will match the majority of endpoints and use a transient local policy if possible + /** + * A policy will be chosen at the time of creating a subscription or publisher. + * A transient local policy will by chosen if it matches with all discovered endpoints, + * otherwise a volatile policy will be chosen. + * + * The middleware is not expected to update the policy after creating a subscription or + * publisher, even if the chosen policy is incompatible with newly discovered endpoints. + * Therefore, this policy should be used with care since non-deterministic behavior + * can occur due to races with discovery. + */ RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE, /// Durability policy has not yet been set @@ -459,6 +479,16 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC = 3, /// Will match the majority of endpoints and use a manual by topic policy if possible + /** + * A policy will be chosen at the time of creating a subscription or publisher. + * A manual by topic policy will by chosen if it matches with all discovered endpoints, + * otherwise an automatic policy will be chosen. + * + * The middleware is not expected to update the policy after creating a subscription or + * publisher, even if the chosen policy is incompatible with newly discovered endpoints. + * Therefore, this policy should be used with care since non-deterministic behavior + * can occur due to races with discovery. + */ RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 4, /// Liveliness policy has not yet been set @@ -468,7 +498,20 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e /// QoS Deadline default. #define RMW_QOS_DEADLINE_DEFAULT RMW_DURATION_UNSPECIFIED /// Will match the majority of endpoints while maintaining as strict a policy as possible -/// Value is RMW_DURATION_INFINITE - 1 +/** + * Value is RMW_DURATION_INFINITE - 1. + * + * A policy will be chosen at the time of creating a subscription or publisher. + * For a subscription, the deadline will be the maximum value of all discovered publisher + * deadlines. + * For a publisher, the deadline will be the minimum value of all discovered subscription + * deadlines. + * + * The middleware is not expected to update the policy after creating a subscription or + * publisher, even if the chosen policy is incompatible with newly discovered endpoints. + * Therefore, this policy should be used with care since non-deterministic behavior + * can occur due to races with discovery. + */ #define RMW_QOS_DEADLINE_BEST_AVAILABLE {9223372036LL, 854775806LL} /// QoS Lifespan default. @@ -477,7 +520,20 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e /// QoS Liveliness lease duration default. #define RMW_QOS_LIVELINESS_LEASE_DURATION_DEFAULT RMW_DURATION_UNSPECIFIED /// Will match the majority of endpoints while maintaining as strict a policy as possible -/// Value is RMW_DURATION_INFINITE - 1 +/** + * Value is RMW_DURATION_INFINITE - 1. + * + * A policy will be chosen at the time of creating a subscription or publisher. + * For a subscription, the lease duration will be the maximum value of all discovered publisher + * lease durations. + * For a publisher, the lease duration will be the minimum value of all discovered subscription + * lease durations. + * + * The middleware is not expected to update the policy after creating a subscription or + * publisher, even if the chosen policy is incompatible with newly discovered endpoints. + * Therefore, this policy should be used with care since non-deterministic behavior + * can occur due to races with discovery. + */ #define RMW_QOS_LIVELINESS_LEASE_DURATION_BEST_AVAILABLE {9223372036LL, 854775806LL} /// ROS MiddleWare quality of service profile. From 9988e8224be2411600de0a7e1fbc08c7410c4b12 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Tue, 19 Apr 2022 14:11:19 -0700 Subject: [PATCH 3/9] Add note about durability behavior with transient local publishers Signed-off-by: Jacob Perron --- rmw/include/rmw/types.h | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index 8644fac9..b6dd6a44 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -432,6 +432,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e * A transient local policy will by chosen if it matches with all discovered endpoints, * otherwise a volatile policy will be chosen. * + * In the case that a volatile policy is chosen for a subscription, any messages sent before + * the subscription was created by transient local publishers will not be received. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior From cf5bcab4d39439b660955a51f2a971611c60e4df Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Tue, 19 Apr 2022 14:17:44 -0700 Subject: [PATCH 4/9] Add note about getting actual QoS policy Signed-off-by: Jacob Perron --- rmw/include/rmw/types.h | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index b6dd6a44..9dd9dab9 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -387,6 +387,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_reliability_policy_e * A reliable policy will by chosen if it matches with all discovered endpoints, * otherwise a best effort policy will be chosen. * + * The actual QoS policy can be retrieved after the endpoint is created with + * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -435,6 +438,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e * In the case that a volatile policy is chosen for a subscription, any messages sent before * the subscription was created by transient local publishers will not be received. * + * The actual QoS policy can be retrieved after the endpoint is created with + * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -487,6 +493,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * A manual by topic policy will by chosen if it matches with all discovered endpoints, * otherwise an automatic policy will be chosen. * + * The actual QoS policy can be retrieved after the endpoint is created with + * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -510,6 +519,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * For a publisher, the deadline will be the minimum value of all discovered subscription * deadlines. * + * The actual QoS policy can be retrieved after the endpoint is created with + * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -532,6 +544,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * For a publisher, the lease duration will be the minimum value of all discovered subscription * lease durations. * + * The actual QoS policy can be retrieved after the endpoint is created with + * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior From f10a8a3a54bfdf13bdc2a9119341476d7fd7e121 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Tue, 19 Apr 2022 15:11:36 -0700 Subject: [PATCH 5/9] Improve documentation of 'best available' profile Signed-off-by: Jacob Perron --- rmw/include/rmw/qos_profiles.h | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/rmw/include/rmw/qos_profiles.h b/rmw/include/rmw/qos_profiles.h index 1cf81df0..b0343507 100644 --- a/rmw/include/rmw/qos_profiles.h +++ b/rmw/include/rmw/qos_profiles.h @@ -101,6 +101,18 @@ static const rmw_qos_profile_t rmw_qos_profile_system_default = }; /// Match majority of endpoints currently available while maintaining the highest level of service +/** + * Reliability, durability, deadline, liveliness, and liveliness lease duration policies will be + * chosen at the time of creating a subscription or publisher. + * + * The actual QoS policy can be retrieved after the endpoint is created with + * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * + * The middleware is not expected to update policies after creating a subscription or + * publisher, even if one or more policies are incompatible with newly discovered endpoints. + * Therefore, this profile should be used with care since non-deterministic behavior + * can occur due to races with discovery. + */ static const rmw_qos_profile_t rmw_qos_profile_best_available = { RMW_QOS_POLICY_HISTORY_KEEP_LAST, From 069042bb6c0bbabfa7908a1fad4ab41fa9b6089c Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Fri, 22 Apr 2022 16:03:17 -0700 Subject: [PATCH 6/9] Change liveliness enum value and update documentation * Avoid changing existing enum values * Clarify that actual reported QoS may be best effort or other values Signed-off-by: Jacob Perron --- rmw/include/rmw/types.h | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index 9dd9dab9..528bfb05 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -387,8 +387,8 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_reliability_policy_e * A reliable policy will by chosen if it matches with all discovered endpoints, * otherwise a best effort policy will be chosen. * - * The actual QoS policy can be retrieved after the endpoint is created with - * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or + * `rmw_publisher_get_actual_qos` may be best available, reliable, or best effort. * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. @@ -438,8 +438,8 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e * In the case that a volatile policy is chosen for a subscription, any messages sent before * the subscription was created by transient local publishers will not be received. * - * The actual QoS policy can be retrieved after the endpoint is created with - * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or + * `rmw_publisher_get_actual_qos` may be best available, transient local, or volatile. * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. @@ -487,24 +487,24 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e // Using `3` for backwards compatibility. RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC = 3, + /// Liveliness policy has not yet been set + RMW_QOS_POLICY_LIVELINESS_UNKNOWN = 4 + /// Will match the majority of endpoints and use a manual by topic policy if possible /** * A policy will be chosen at the time of creating a subscription or publisher. * A manual by topic policy will by chosen if it matches with all discovered endpoints, * otherwise an automatic policy will be chosen. * - * The actual QoS policy can be retrieved after the endpoint is created with - * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or + * `rmw_publisher_get_actual_qos` may be best available, automatic, or manual by topic. * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior * can occur due to races with discovery. */ - RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 4, - - /// Liveliness policy has not yet been set - RMW_QOS_POLICY_LIVELINESS_UNKNOWN = 5 + RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 5, } rmw_qos_liveliness_policy_t; /// QoS Deadline default. @@ -519,8 +519,8 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * For a publisher, the deadline will be the minimum value of all discovered subscription * deadlines. * - * The actual QoS policy can be retrieved after the endpoint is created with - * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or + * `rmw_publisher_get_actual_qos` may be best available or the actual deadline value. * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. @@ -544,8 +544,8 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * For a publisher, the lease duration will be the minimum value of all discovered subscription * lease durations. * - * The actual QoS policy can be retrieved after the endpoint is created with - * `rmw_get_subscriptions_info_by_topic` or `rmw_get_publishers_info_by_topic`. + * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or + * `rmw_publisher_get_actual_qos` may be best available or the actual lease duration value. * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. From 6dc811d5bc12788972ef7a08a46b57c8f0e88676 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Mon, 25 Apr 2022 11:07:34 -0700 Subject: [PATCH 7/9] Fix comma Signed-off-by: Jacob Perron --- rmw/include/rmw/types.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index 528bfb05..996e8b8b 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -488,7 +488,7 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC = 3, /// Liveliness policy has not yet been set - RMW_QOS_POLICY_LIVELINESS_UNKNOWN = 4 + RMW_QOS_POLICY_LIVELINESS_UNKNOWN = 4, /// Will match the majority of endpoints and use a manual by topic policy if possible /** @@ -504,7 +504,7 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * Therefore, this policy should be used with care since non-deterministic behavior * can occur due to races with discovery. */ - RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 5, + RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE = 5 } rmw_qos_liveliness_policy_t; /// QoS Deadline default. From 95241adf07ddccef32b5ef5862a329c048640341 Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Mon, 25 Apr 2022 11:13:02 -0700 Subject: [PATCH 8/9] Make best available enum value last to minimize disruption In case users are relying on integer values. Signed-off-by: Jacob Perron --- rmw/include/rmw/types.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index 996e8b8b..3a90c6f9 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -381,6 +381,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_reliability_policy_e /// Attempt to deliver samples, but some may be lost if the network is not robust RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT, + /// Reliability policy has not yet been set + RMW_QOS_POLICY_RELIABILITY_UNKNOWN, + /// Will match the majority of endpoints and use a reliable policy if possible /** * A policy will be chosen at the time of creating a subscription or publisher. @@ -395,10 +398,7 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_reliability_policy_e * Therefore, this policy should be used with care since non-deterministic behavior * can occur due to races with discovery. */ - RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE, - - /// Reliability policy has not yet been set - RMW_QOS_POLICY_RELIABILITY_UNKNOWN + RMW_QOS_POLICY_RELIABILITY_BEST_AVAILABLE } rmw_qos_reliability_policy_t; /// QoS history enumerations describing how samples endure @@ -429,6 +429,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e /// Samples are not persistent RMW_QOS_POLICY_DURABILITY_VOLATILE, + /// Durability policy has not yet been set + RMW_QOS_POLICY_DURABILITY_UNKNOWN, + /// Will match the majority of endpoints and use a transient local policy if possible /** * A policy will be chosen at the time of creating a subscription or publisher. @@ -446,10 +449,7 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e * Therefore, this policy should be used with care since non-deterministic behavior * can occur due to races with discovery. */ - RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE, - - /// Durability policy has not yet been set - RMW_QOS_POLICY_DURABILITY_UNKNOWN + RMW_QOS_POLICY_DURABILITY_BEST_AVAILABLE } rmw_qos_durability_policy_t; #define RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_NODE_DEPRECATED_MSG \ From 492c48fdf9a94e4c490eeb5a534eaa76ab59034e Mon Sep 17 00:00:00 2001 From: Jacob Perron Date: Mon, 25 Apr 2022 17:08:12 -0700 Subject: [PATCH 9/9] Document behavior for services Signed-off-by: Jacob Perron --- rmw/include/rmw/types.h | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index 3a90c6f9..59f261d1 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -393,6 +393,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_reliability_policy_e * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or * `rmw_publisher_get_actual_qos` may be best available, reliable, or best effort. * + * Services and clients are not supported and default to the reliability value in + * `rmw_qos_profile_services_default`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -444,6 +447,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_durability_policy_e * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or * `rmw_publisher_get_actual_qos` may be best available, transient local, or volatile. * + * Services and clients are not supported and default to the durability value in + * `rmw_qos_profile_services_default`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -499,6 +505,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or * `rmw_publisher_get_actual_qos` may be best available, automatic, or manual by topic. * + * Services and clients are not supported and default to the liveliness value in + * `rmw_qos_profile_services_default`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -522,6 +531,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or * `rmw_publisher_get_actual_qos` may be best available or the actual deadline value. * + * Services and clients are not supported and default to the deadline value in + * `rmw_qos_profile_services_default`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior @@ -547,6 +559,9 @@ typedef enum RMW_PUBLIC_TYPE rmw_qos_liveliness_policy_e * The QoS policy reported by functions like `rmw_subscription_get_actual_qos` or * `rmw_publisher_get_actual_qos` may be best available or the actual lease duration value. * + * Services and clients are not supported and default to the lease duration value in + * `rmw_qos_profile_services_default`. + * * The middleware is not expected to update the policy after creating a subscription or * publisher, even if the chosen policy is incompatible with newly discovered endpoints. * Therefore, this policy should be used with care since non-deterministic behavior