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_COMPONENT 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 // Called by muxer once StartupTracing is started. It will be called before 67 // SetupStartupTracingBlocking is returned. OnStartupTracingSetup()68 virtual void OnStartupTracingSetup() {} 69 70 // The lifecycle methods below are always called in the following sequence: 71 // SetupDataSource -> StartDataSource -> StopDataSource. 72 // Or, in the edge case where a trace is aborted immediately: 73 // SetupDataSource -> StopDataSource. 74 // The Setup+Start call sequence is always guaranateed, regardless of the 75 // TraceConfig.deferred_start flags. 76 // Called by the Service to configure one of the data sources previously 77 // registered through TracingService::ProducerEndpoint::RegisterDataSource(). 78 // This method is always called before StartDataSource. There is always a 79 // SetupDataSource() call before each StartDataSource() call. 80 // Args: 81 // - DataSourceInstanceID is an identifier chosen by the Service that should 82 // be assigned to the newly created data source instance. It is used to 83 // match the StopDataSource() request below. 84 // - DataSourceConfig is the configuration for the new data source (e.g., 85 // tells which trace categories to enable). 86 virtual void SetupDataSource(DataSourceInstanceID, 87 const DataSourceConfig&) = 0; 88 89 // Called by the Service to turn on one of the data sources previously 90 // registered through TracingService::ProducerEndpoint::RegisterDataSource() 91 // and initialized through SetupDataSource(). 92 // Both arguments are guaranteed to be identical to the ones passed to the 93 // prior SetupDataSource() call. 94 virtual void StartDataSource(DataSourceInstanceID, 95 const DataSourceConfig&) = 0; 96 97 // Called by the Service to shut down an existing data source instance. 98 virtual void StopDataSource(DataSourceInstanceID) = 0; 99 100 // Called by the service to request the Producer to commit the data of the 101 // given data sources and return their chunks into the shared memory buffer. 102 // The Producer is expected to invoke NotifyFlushComplete(FlushRequestID) on 103 // the Service after the data has been committed. The producer has to either 104 // reply to the flush requests in order, or can just reply to the latest one 105 // Upon seeing a NotifyFlushComplete(N), the service will assume that all 106 // flushes < N have also been committed. 107 virtual void Flush(FlushRequestID, 108 const DataSourceInstanceID* data_source_ids, 109 size_t num_data_sources) = 0; 110 111 // Called by the service to instruct the given data sources to stop referring 112 // to any trace contents emitted so far. The intent is that after processing 113 // this call, the rest of the trace should be parsable even if all of the 114 // packets emitted so far have been lost (for example due to ring buffer 115 // overwrites). 116 // 117 // Called only for Producers with active data sources that have opted in by 118 // setting |handles_incremental_state_clear| in their DataSourceDescriptor. 119 // 120 // The way this call is handled is up to the individual Producer 121 // implementation. Some might wish to emit invalidation markers in the trace 122 // (see TracePacket.incremental_state_cleared for an existing field), and 123 // handle them when parsing the trace. 124 virtual void ClearIncrementalState( 125 const DataSourceInstanceID* data_source_ids, 126 size_t num_data_sources) = 0; 127 }; 128 129 } // namespace perfetto 130 131 #endif // INCLUDE_PERFETTO_EXT_TRACING_CORE_PRODUCER_H_ 132