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