Coverage Report

Created: 2022-08-24 06:19

/src/Fast-DDS/include/fastdds/rtps/history/IPayloadPool.h
Line
Count
Source (jump to first uncovered line)
1
// Copyright 2020 Proyectos y Sistemas de Mantenimiento SL (eProsima).
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//     http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14
15
/**
16
 * @file IPayloadPool.h
17
 */
18
19
#ifndef _FASTDDS_RTPS_HISTORY_IPAYLOADPOOL_H_
20
#define _FASTDDS_RTPS_HISTORY_IPAYLOADPOOL_H_
21
22
#include <fastdds/rtps/common/SerializedPayload.h>
23
24
#include <cstdint>
25
#include <memory>
26
27
namespace eprosima {
28
namespace fastrtps {
29
namespace rtps {
30
31
struct CacheChange_t;
32
33
/**
34
 * An interface for classes responsible of serialized payload management.
35
 */
36
class IPayloadPool
37
{
38
public:
39
40
0
    virtual ~IPayloadPool() = default;
41
42
    /**
43
     * @brief Get a serialized payload for a new sample.
44
     *
45
     * This method will usually be called in one of the following situations:
46
     *     @li When a writer creates a new cache change
47
     *     @li When a reader receives the first fragment of a cache change
48
     *
49
     * In both cases, the received @c size will be for the whole serialized payload.
50
     *
51
     * @param [in]     size          Number of bytes required for the serialized payload.
52
     *                               Should be greater than 0.
53
     * @param [in,out] cache_change  Cache change to assign the payload to
54
     *
55
     * @returns whether the operation succeeded or not
56
     *
57
     * @pre Fields @c writerGUID and @c sequenceNumber of @c cache_change are either:
58
     *     @li Both equal to @c unknown (meaning a writer is creating a new change)
59
     *     @li Both different from @c unknown (meaning a reader has received the first fragment of a cache change)
60
     *
61
     * @post
62
     *     @li Field @c cache_change.payload_owner equals this
63
     *     @li Field @c serializedPayload.data points to a buffer of at least @c size bytes
64
     *     @li Field @c serializedPayload.max_size is greater than or equal to @c size
65
     */
66
    virtual bool get_payload(
67
            uint32_t size,
68
            CacheChange_t& cache_change) = 0;
69
70
    /**
71
     * @brief Assign a serialized payload to a new sample.
72
     *
73
     * This method will usually be called when a reader receives a whole cache change.
74
     *
75
     * @param [in,out] data          Serialized payload received
76
     * @param [in,out] data_owner    Payload pool owning incoming data
77
     * @param [in,out] cache_change  Cache change to assign the payload to
78
     *
79
     * @returns whether the operation succeeded or not
80
     *
81
     * @note @c data and @c data_owner are received as references to accommodate the case where several readers
82
     * receive the same payload. If the payload has no owner, it means it is allocated on the stack of a
83
     * reception thread, and a copy should be performed. The pool may decide in that case to point @c data.data
84
     * to the new copy and take ownership of the payload. In that case, when the reception thread is done with
85
     * the payload (after all readers have been informed of the received data), method @c release_payload will be
86
     * called to indicate that the reception thread is not using the payload anymore.
87
     *
88
     * @warning @c data_owner can only be changed from @c nullptr to @c this. If a value different from
89
     * @c nullptr is received it should be left unchanged.
90
     *
91
     * @warning @c data fields can only be changed when @c data_owner is @c nullptr. If a value different from
92
     * @c nullptr is received all fields in @c data should be left unchanged.
93
     *
94
     * @pre
95
     *     @li Field @c cache_change.writerGUID is not @c unknown
96
     *     @li Field @c cache_change.sequenceNumber is not @c unknown
97
     *
98
     * @post
99
     *     @li Field @c cache_change.payload_owner equals this
100
     *     @li Field @c cache_change.serializedPayload.data points to a buffer of at least @c data.length bytes
101
     *     @li Field @c cache_change.serializedPayload.length is equal to @c data.length
102
     *     @li Field @c cache_change.serializedPayload.max_size is greater than or equal to @c data.length
103
     *     @li Content of @c cache_change.serializedPayload.data is the same as @c data.data
104
     */
105
    virtual bool get_payload(
106
            SerializedPayload_t& data,
107
            IPayloadPool*& data_owner,
108
            CacheChange_t& cache_change) = 0;
109
110
    /**
111
     * @brief Release a serialized payload from a sample.
112
     *
113
     * This method will be called when a cache change is removed from a history.
114
     *
115
     * @param [in,out] cache_change  Cache change to assign the payload to
116
     *
117
     * @returns whether the operation succeeded or not
118
     *
119
     * @pre @li Field @c payload_owner of @c cache_change equals this
120
     *
121
     * @post @li Field @c payload_owner of @c cache_change is @c nullptr
122
     */
123
    virtual bool release_payload(
124
            CacheChange_t& cache_change) = 0;
125
};
126
127
} /* namespace rtps */
128
} /* namespace fastrtps */
129
} /* namespace eprosima */
130
131
132
#endif /* _FASTDDS_RTPS_HISTORY_IPAYLOADPOOL_H_ */