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 class PERFETTO_EXPORT TracingBackend { 47 public: 48 virtual ~TracingBackend(); 49 50 // Connects a Producer instance and obtains a ProducerEndpoint, which is 51 // essentially a 1:1 channel between one Producer and the Service. 52 // To disconnect just destroy the returned endpoint object. It is safe to 53 // destroy the Producer once Producer::OnDisconnect() has been invoked. 54 struct ConnectProducerArgs { 55 std::string producer_name; 56 57 // The Producer object that will receive calls like Start/StopDataSource(). 58 // The caller has to guarantee that this object is valid as long as the 59 // returned ProducerEndpoint is alive. 60 Producer* producer = nullptr; 61 62 // The task runner where the Producer methods will be called onto. 63 // The caller has to guarantee that the passed TaskRunner is valid as long 64 // as the returned ProducerEndpoint is alive. 65 ::perfetto::base::TaskRunner* task_runner = nullptr; 66 67 // These get propagated from TracingInitArgs and are optionally provided by 68 // the client when calling Tracing::Initialize(). 69 uint32_t shmem_size_hint_bytes = 0; 70 uint32_t shmem_page_size_hint_bytes = 0; 71 }; 72 73 virtual std::unique_ptr<ProducerEndpoint> ConnectProducer( 74 const ConnectProducerArgs&) = 0; 75 76 // As above, for the Consumer-side. 77 struct ConnectConsumerArgs { 78 // The Consumer object that will receive calls like OnTracingDisabled(), 79 // OnTraceData(). 80 Consumer* consumer{}; 81 82 // The task runner where the Consumer methods will be called onto. 83 ::perfetto::base::TaskRunner* task_runner{}; 84 }; 85 virtual std::unique_ptr<ConsumerEndpoint> ConnectConsumer( 86 const ConnectConsumerArgs&) = 0; 87 }; 88 89 } // namespace perfetto 90 91 #endif // INCLUDE_PERFETTO_TRACING_TRACING_BACKEND_H_ 92