1 /* 2 * Copyright (C) 2017 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_EXT_TRACING_CORE_PRODUCER_H_ 18 #define INCLUDE_PERFETTO_EXT_TRACING_CORE_PRODUCER_H_ 19 20 #include "perfetto/base/export.h" 21 #include "perfetto/ext/tracing/core/basic_types.h" 22 #include "perfetto/tracing/core/flush_flags.h" 23 #include "perfetto/tracing/core/forward_decls.h" 24 25 namespace perfetto { 26 27 class SharedMemory; 28 29 // A Producer is an entity that connects to the write-only port of the Service 30 // and exposes the ability to produce performance data on-demand. The lifecycle 31 // of a Producer is as follows: 32 // 1. The producer connects to the service and advertises its data sources 33 // (e.g., the ability to get kernel ftraces, to list process stats). 34 // 2. The service acknowledges the connection and sends over the SharedMemory 35 // region that will be used to exchange data (together with the signalling 36 // API TracingService::ProducerEndpoint::OnPageAcquired()/OnPageReleased()). 37 // 3. At some point later on, the Service asks the Producer to turn on some of 38 // the previously registered data sources, together with some configuration 39 // parameters. This happens via the StartDataSource() callback. 40 // 4. In response to that the Producer will spawn an instance of the given data 41 // source and inject its data into the shared memory buffer (obtained during 42 // OnConnect). 43 // This interface is subclassed by: 44 // 1. The actual producer code in the clients e.g., the ftrace reader process. 45 // 2. The transport layer when interposing RPC between service and producers. 46 class PERFETTO_EXPORT_COMPONENT Producer { 47 public: 48 virtual ~Producer(); 49 50 // Called by Service (or more typically by the transport layer, on behalf of 51 // the remote Service), once the Producer <> Service connection has been 52 // established. 53 virtual void OnConnect() = 0; 54 55 // Called by the Service or by the transport layer if the connection with the 56 // service drops, either voluntarily (e.g., by destroying the ProducerEndpoint 57 // obtained through Service::ConnectProducer()) or involuntarily (e.g., if the 58 // Service process crashes). 59 // The Producer is expected to tear down all its data sources if this happens. 60 // Once this call returns it is possible to safely destroy the Producer 61 // instance. 62 virtual void OnDisconnect() = 0; 63 64 // Called by the Service after OnConnect but before the first DataSource is 65 // created. Can be used for any setup required before tracing begins. 66 virtual void OnTracingSetup() = 0; 67 68 // Called by muxer once StartupTracing is started. It will be called before 69 // SetupStartupTracingBlocking is returned. OnStartupTracingSetup()70 virtual void OnStartupTracingSetup() {} 71 72 // The lifecycle methods below are always called in the following sequence: 73 // SetupDataSource -> StartDataSource -> StopDataSource. 74 // Or, in the edge case where a trace is aborted immediately: 75 // SetupDataSource -> StopDataSource. 76 // The Setup+Start call sequence is always guaranateed, regardless of the 77 // TraceConfig.deferred_start flags. 78 // Called by the Service to configure one of the data sources previously 79 // registered through TracingService::ProducerEndpoint::RegisterDataSource(). 80 // This method is always called before StartDataSource. There is always a 81 // SetupDataSource() call before each StartDataSource() call. 82 // Args: 83 // - DataSourceInstanceID is an identifier chosen by the Service that should 84 // be assigned to the newly created data source instance. It is used to 85 // match the StopDataSource() request below. 86 // - DataSourceConfig is the configuration for the new data source (e.g., 87 // tells which trace categories to enable). 88 virtual void SetupDataSource(DataSourceInstanceID, 89 const DataSourceConfig&) = 0; 90 91 // Called by the Service to turn on one of the data sources previously 92 // registered through TracingService::ProducerEndpoint::RegisterDataSource() 93 // and initialized through SetupDataSource(). 94 // Both arguments are guaranteed to be identical to the ones passed to the 95 // prior SetupDataSource() call. 96 virtual void StartDataSource(DataSourceInstanceID, 97 const DataSourceConfig&) = 0; 98 99 // Called by the Service to shut down an existing data source instance. 100 virtual void StopDataSource(DataSourceInstanceID) = 0; 101 102 // Called by the service to request the Producer to commit the data of the 103 // given data sources and return their chunks into the shared memory buffer. 104 // The Producer is expected to invoke NotifyFlushComplete(FlushRequestID) on 105 // the Service after the data has been committed. The producer has to either 106 // reply to the flush requests in order, or can just reply to the latest one 107 // Upon seeing a NotifyFlushComplete(N), the service will assume that all 108 // flushes < N have also been committed. 109 virtual void Flush(FlushRequestID, 110 const DataSourceInstanceID* data_source_ids, 111 size_t num_data_sources, 112 FlushFlags) = 0; 113 114 // Called by the service to instruct the given data sources to stop referring 115 // to any trace contents emitted so far. The intent is that after processing 116 // this call, the rest of the trace should be parsable even if all of the 117 // packets emitted so far have been lost (for example due to ring buffer 118 // overwrites). 119 // 120 // Called only for Producers with active data sources that have opted in by 121 // setting |handles_incremental_state_clear| in their DataSourceDescriptor. 122 // 123 // The way this call is handled is up to the individual Producer 124 // implementation. Some might wish to emit invalidation markers in the trace 125 // (see TracePacket.incremental_state_cleared for an existing field), and 126 // handle them when parsing the trace. 127 virtual void ClearIncrementalState( 128 const DataSourceInstanceID* data_source_ids, 129 size_t num_data_sources) = 0; 130 }; 131 132 } // namespace perfetto 133 134 #endif // INCLUDE_PERFETTO_EXT_TRACING_CORE_PRODUCER_H_ 135