1 /* 2 * Copyright (C) 2019 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_TRACING_BACKEND_H_ 18 #define INCLUDE_PERFETTO_TRACING_TRACING_BACKEND_H_ 19 20 #include <memory> 21 #include <string> 22 23 #include "perfetto/base/export.h" 24 25 // The embedder can (but doesn't have to) extend the TracingBackend class and 26 // pass as an argument to Tracing::Initialize(kCustomBackend) to override the 27 // way to reach the service. This is for peculiar cases where the embedder has 28 // a multi-process architecture and wants to override the IPC transport. The 29 // real use-case for this at the time of writing is chromium (+ Mojo IPC). 30 // Extending this class requires depending on the full set of perfetto headers 31 // (not just /public/). Contact the team before doing so as the non-public 32 // headers are not guaranteed to be API stable. 33 34 namespace perfetto { 35 36 namespace base { 37 class TaskRunner; 38 } 39 40 // These classes are declared in headers outside of /public/. 41 class Consumer; 42 class ConsumerEndpoint; 43 class Producer; 44 class ProducerEndpoint; 45 46 // Responsible for connecting to the producer. 47 class PERFETTO_EXPORT_COMPONENT TracingProducerBackend { 48 public: 49 virtual ~TracingProducerBackend(); 50 51 // Connects a Producer instance and obtains a ProducerEndpoint, which is 52 // essentially a 1:1 channel between one Producer and the Service. 53 // To disconnect just destroy the returned endpoint object. It is safe to 54 // destroy the Producer once Producer::OnDisconnect() has been invoked. 55 struct ConnectProducerArgs { 56 std::string producer_name; 57 58 // The Producer object that will receive calls like Start/StopDataSource(). 59 // The caller has to guarantee that this object is valid as long as the 60 // returned ProducerEndpoint is alive. 61 Producer* producer = nullptr; 62 63 // The task runner where the Producer methods will be called onto. 64 // The caller has to guarantee that the passed TaskRunner is valid as long 65 // as the returned ProducerEndpoint is alive. 66 ::perfetto::base::TaskRunner* task_runner = nullptr; 67 68 // These get propagated from TracingInitArgs and are optionally provided by 69 // the client when calling Tracing::Initialize(). 70 uint32_t shmem_size_hint_bytes = 0; 71 uint32_t shmem_page_size_hint_bytes = 0; 72 73 // If true, the backend should allocate a shared memory buffer and provide 74 // it to the service when connecting. 75 // It's used in startup tracing. 76 bool use_producer_provided_smb = false; 77 }; 78 79 virtual std::unique_ptr<ProducerEndpoint> ConnectProducer( 80 const ConnectProducerArgs&) = 0; 81 }; 82 83 // Responsible for connecting to the consumer. 84 class PERFETTO_EXPORT_COMPONENT TracingConsumerBackend { 85 public: 86 virtual ~TracingConsumerBackend(); 87 88 // As above, for the Consumer-side. 89 struct ConnectConsumerArgs { 90 // The Consumer object that will receive calls like OnTracingDisabled(), 91 // OnTraceData(). 92 Consumer* consumer{}; 93 94 // The task runner where the Consumer methods will be called onto. 95 ::perfetto::base::TaskRunner* task_runner{}; 96 }; 97 virtual std::unique_ptr<ConsumerEndpoint> ConnectConsumer( 98 const ConnectConsumerArgs&) = 0; 99 }; 100 101 class PERFETTO_EXPORT_COMPONENT TracingBackend : public TracingProducerBackend, 102 public TracingConsumerBackend { 103 public: 104 ~TracingBackend() override; 105 }; 106 107 } // namespace perfetto 108 109 #endif // INCLUDE_PERFETTO_TRACING_TRACING_BACKEND_H_ 110