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