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