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 Service::ProducerEndpoint::OnPageAcquired()/OnPageReleased()). 36 // 3. At some point later on, the Service asks the Producer to on turn some of 37 // the previously registered data sources, together with some configuration 38 // parameters. This happens via the CreateDataSourceInstance() 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 // TODO(primiano): rename the methods below to Start/StopDataSourceInstance 64 // in the next CLs. 65 66 // Called by the Service to turn on one of the data source previously 67 // registered through Service::ProducerEndpoint::RegisterDataSource(). 68 // Args: 69 // - DataSourceInstanceID is an identifier chosen by the Service that should 70 // be assigned to the newly created data source instance. It is used to 71 // match the TearDownDataSourceInstance() request below. 72 // - DataSourceConfig is the configuration for the new data source (e.g., 73 // tells which trace categories to enable). 74 virtual void CreateDataSourceInstance(DataSourceInstanceID, 75 const DataSourceConfig&) = 0; 76 77 // Called by the Service to shut down an existing data source instance. 78 virtual void TearDownDataSourceInstance(DataSourceInstanceID) = 0; 79 80 // Called by the Service after OnConnect but before the first DataSource is 81 // created. Can be used for any setup required before tracing begins. 82 virtual void OnTracingSetup() = 0; 83 84 // Called by the service to request the Producer to commit the data of the 85 // given data sources and return their chunks into the shared memory buffer. 86 // The Producer is expected to invoke NotifyFlushComplete(FlushRequestID) on 87 // the Service after the data has been committed. The producer has to either 88 // reply to the flush requests in order, or can just reply to the latest one 89 // Upon seeing a NotifyFlushComplete(N), the service will assume that all 90 // flushes < N have also been committed. 91 virtual void Flush(FlushRequestID, 92 const DataSourceInstanceID* data_source_ids, 93 size_t num_data_sources) = 0; 94 }; 95 96 } // namespace perfetto 97 98 #endif // INCLUDE_PERFETTO_TRACING_CORE_PRODUCER_H_ 99