1 // Copyright 2021 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://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, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 #include "pw_multisink/multisink.h" 17 #include "pw_status/status.h" 18 19 namespace pw { 20 namespace multisink { 21 22 // An asynchronous reader which is attached to a MultiSink via AttachDrain. 23 // Each Drain holds a PrefixedEntryRingBufferMulti::Reader and abstracts away 24 // entry sequence information for clients. 25 class Drain { 26 public: Drain()27 constexpr Drain() : last_handled_sequence_id_(0), multisink_(nullptr) {} 28 29 // Returns the next available entry if it exists and acquires the latest drop 30 // count in parallel. 31 // 32 // The `drop_count_out` is set to the number of entries that were dropped 33 // since the last call to GetEntry, if the read operation was successful or 34 // indicated that no entries were available to read. If the read operation 35 // fails otherwise, the `drop_count_out` is set to zero. 36 // 37 // Drop counts are internally maintained with a 32-bit counter. If UINT32_MAX 38 // entries have been handled by the attached multisink between subsequent 39 // calls to GetEntry, the drop count will overflow and will report a lower 40 // count erroneously. Users should ensure that sinks call GetEntry 41 // at least once every UINT32_MAX entries. 42 // 43 // Return values: 44 // Ok - An entry was successfully read from the multisink. The drop_count_out 45 // is set to the count of entries that were dropped since the last call 46 // to GetEntry. 47 // FailedPrecondition - The drain must be attached to a sink. 48 // OutOfRange - No entries were available, the drop_count_out is set to the 49 // number of entries that were dropped since the last call to GetEntry. 50 // ResourceExhausted - The provided buffer was not large enough to store the 51 // next available entry. 52 // DataLoss - An entry was read from the multisink, but did not match the 53 // expected format (i.e. failed to decode). 54 // InvalidArgument - The drain is not currently associated with a multisink. 55 Result<ConstByteSpan> GetEntry(ByteSpan entry, uint32_t& drop_count_out); 56 57 protected: 58 friend MultiSink; 59 ring_buffer::PrefixedEntryRingBufferMulti::Reader reader_; 60 uint32_t last_handled_sequence_id_; 61 MultiSink* multisink_; 62 }; 63 64 } // namespace multisink 65 } // namespace pw 66