1 /* 2 * Copyright (C) 2019 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef INCLUDE_PERFETTO_TRACING_TRACE_WRITER_BASE_H_ 18 #define INCLUDE_PERFETTO_TRACING_TRACE_WRITER_BASE_H_ 19 20 #include <cstdint> 21 #include "perfetto/base/export.h" 22 #include "perfetto/protozero/message_handle.h" 23 24 namespace perfetto { 25 26 namespace protos { 27 namespace pbzero { 28 class TracePacket; 29 } // namespace pbzero 30 } // namespace protos 31 32 // This is a single-thread write interface that allows to write protobufs 33 // directly into the tracing shared buffer without making any copies. 34 // The idea is that each data source creates one (or more) TraceWriter for each 35 // thread it wants to write from. Each TraceWriter will get its own dedicated 36 // chunk and will write into the shared buffer without any locking most of the 37 // time. 38 39 class PERFETTO_EXPORT_COMPONENT TraceWriterBase { 40 public: 41 virtual ~TraceWriterBase(); 42 43 // Creates a new trace packet and returns a handle to a protozero Message that 44 // will write to it. The message will be finalized either by calling directly 45 // handle.Finalize() or by letting the handle go out of scope (the message 46 // should be finalized before a new call to NewTracePacket is made). The 47 // returned handle can be std::move()'d but cannot be used after either: (i) 48 // the TraceWriter instance is destroyed, (ii) a subsequence NewTracePacket() 49 // call is made on the same TraceWriter instance. 50 // 51 // The caller can use protozero::MessageHandle::TakeStreamWriter() to write. 52 // 53 // The caller must call ->Finalize() on the returned trace packet (the handle 54 // destructor will take care of that) or explicitly call FinishTracePacket (if 55 // using TakeStreamWriter) before calling any method on the same TraceWriter 56 // instance. 57 // 58 // The returned packet handle is always valid, but note that, when using 59 // BufferExhaustedPolicy::kDrop and the SMB is exhausted, it may be assigned 60 // a garbage chunk and any trace data written into it will be lost. For more 61 // details on buffer size choices: https://perfetto.dev/docs/concepts/buffers. 62 virtual protozero::MessageHandle<protos::pbzero::TracePacket> 63 NewTracePacket() = 0; 64 65 // Tells the TraceWriterBase that the previous packet started with 66 // NewTracePacket() is finished. 67 // 68 // Calling this is optional: the TraceWriterBase can realize that the previous 69 // packet is finished when the next NewTracePacket() is called. It is still 70 // useful, because the next NewTracePacket may not happen for a while. 71 virtual void FinishTracePacket() = 0; 72 73 // Commits the data pending for the current chunk. This can be called 74 // only if the handle returned by NewTracePacket() has been destroyed (i.e. we 75 // cannot Flush() while writing a TracePacket). 76 // 77 // Note: Flush() also happens implicitly when destroying the TraceWriter. 78 // 79 // |callback| is an optional callback. When non-null it will request the 80 // service to ACK the flush and will be invoked after the service has 81 // acknowledged it. The callback might be NEVER INVOKED if the service crashes 82 // or the IPC connection is dropped. The callback should be used only by tests 83 // and best-effort features (logging). 84 virtual void Flush(std::function<void()> callback = {}) = 0; 85 86 // Bytes written since creation. Not reset when new chunks are acquired. 87 virtual uint64_t written() const = 0; 88 89 // Number of times the trace writer entered a mode in which it started 90 // dropping data. 91 // 92 // This does not necessarily correspond to the number of packets/chunks 93 // dropped, as multiple such packets/chunks can be dropped on entry into a 94 // drop data mode. 95 virtual uint64_t drop_count() const = 0; 96 }; 97 98 } // namespace perfetto 99 100 #endif // INCLUDE_PERFETTO_TRACING_TRACE_WRITER_BASE_H_ 101