From 7810f901cf1a845814bbc6b21a3390b40a5adf39 Mon Sep 17 00:00:00 2001 From: Ivan Santiago Paunovic Date: Fri, 4 Mar 2022 14:43:17 -0300 Subject: [PATCH] Add more requirements to what a rmw implementation can expose as a sequence number Signed-off-by: Ivan Santiago Paunovic --- rmw/include/rmw/types.h | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/rmw/include/rmw/types.h b/rmw/include/rmw/types.h index cd250b97..6e88ed36 100644 --- a/rmw/include/rmw/types.h +++ b/rmw/include/rmw/types.h @@ -538,18 +538,40 @@ typedef struct RMW_PUBLIC_TYPE rmw_message_info_s /** * This sequence number is set by the publisher and therefore uniquely identifies * a message when combined with the publisher GID. + * For long running applications, the sequence number might wrap arround at some point. * * If the rmw implementation doesn't support sequence numbers, it's value will be * RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED. + * + * Requirements: + * + * If `psn1` and `psn2` are the publication sequence numbers obtained by + * calls to `rmw_take*()`, where `psn1` was obtained in a call that happened before `psn2` and both + * sequence numbers are from the same publisher (i.e. also same publisher gid), then: + * + * - psn2 > psn1 (except in the case of a wrap around) + * - `psn2 - psn1 - 1` is the number of messages the publisher sent in the middle of both + * received messages. + * Those might have already been taken by other `rmw_take*()` calls that happened in between or lost. + * `psn2 - psn1 - 1 = 0` if and only if the messages were sent by the publisher consecutively. */ int64_t publication_sequence_number; /// Sequence number of the received message set by the subscription. /** * This sequence number is set by the subscription regardless of which * publish sent the message. + * For long running applications, the sequence number might wrap arround at some point. * * If the rmw implementation doesn't support sequence numbers, it's value will be * RMW_MESSAGE_INFO_SEQUENCE_NUMBER_UNSUPPORTED. + * + * Requirements: + * + * If `rsn1` and `rsn2` are the reception sequence numbers obtained by + * calls to `rmw_take*()`, where `rsn1` was obtained in a call that happened before `rsn2`, then: + * + * - rsn2 > rsn1 (except in the case of a wrap around) + * - `rsn2 = rsn1 + 1` if and only if both `rmw_take*()` calls happened consecutively. */ int64_t reception_sequence_number; /// Global unique identifier of the publisher that sent the message.