include/perfetto/tracing/core/service.h

/*
 * Copyright (C) 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef INCLUDE_PERFETTO_TRACING_CORE_SERVICE_H_
#define INCLUDE_PERFETTO_TRACING_CORE_SERVICE_H_

#include <stdint.h>

#include <functional>
#include <memory>
#include <vector>

#include "perfetto/base/export.h"
#include "perfetto/base/scoped_file.h"
#include "perfetto/tracing/core/basic_types.h"
#include "perfetto/tracing/core/shared_memory.h"

namespace perfetto {

namespace base {
class TaskRunner;
}  // namespace base

class CommitDataRequest;
class Consumer;
class DataSourceDescriptor;
class Producer;
class TraceConfig;
class TraceWriter;

// TODO: for the moment this assumes that all the calls hapen on the same
// thread/sequence. Not sure this will be the case long term in Chrome.

// The public API of the tracing Service business logic.
//
// Exposed to:
// 1. The transport layer (e.g., src/unix_rpc/unix_service_host.cc),
//    which forwards commands received from a remote producer or consumer to
//    the actual service implementation.
// 2. Tests.
//
// Subclassed by:
//   The service business logic in src/core/service_impl.cc.
class PERFETTO_EXPORT Service {
 public:
  // The API for the Producer port of the Service.
  // Subclassed by:
  // 1. The service_impl.cc business logic when returning it in response to
  //    the ConnectProducer() method.
  // 2. The transport layer (e.g., src/ipc) when the producer and
  //    the service don't talk locally but via some IPC mechanism.
  class ProducerEndpoint {
   public:
    virtual ~ProducerEndpoint();

    // Called by the Producer to (un)register data sources. Data sources are
    // identified by their name (i.e. DataSourceDescriptor.name)
    virtual void RegisterDataSource(const DataSourceDescriptor&) = 0;
    virtual void UnregisterDataSource(const std::string& name) = 0;

    // Called by the Producer to signal that some pages in the shared memory
    // buffer (shared between Service and Producer) have changed.
    using CommitDataCallback = std::function<void()>;
    virtual void CommitData(const CommitDataRequest&,
                            CommitDataCallback callback = {}) = 0;

    virtual SharedMemory* shared_memory() const = 0;

    // Size of shared memory buffer pages. It's always a multiple of 4K.
    // See shared_memory_abi.h
    virtual size_t shared_buffer_page_size_kb() const = 0;

    // Creates a trace writer, which allows to create events, handling the
    // underying shared memory buffer and signalling to the Service. This method
    // is thread-safe but the returned object is not. A TraceWriter should be
    // used only from a single thread, or the caller has to handle sequencing
    // via a mutex or equivalent.
    // Args:
    // |target_buffer| is the target buffer ID where the data produced by the
    // writer should be stored by the tracing service. This value is passed
    // upon creation of the data source (CreateDataSourceInstance()) in the
    // DataSourceConfig.target_buffer().
    virtual std::unique_ptr<TraceWriter> CreateTraceWriter(
        BufferID target_buffer) = 0;

    // Called in response to a Producer::Flush(request_id) call after all data
    // for the flush request has been committed.
    virtual void NotifyFlushComplete(FlushRequestID) = 0;
  };  // class ProducerEndpoint.

  // The API for the Consumer port of the Service.
  // Subclassed by:
  // 1. The service_impl.cc business logic when returning it in response to
  //    the ConnectConsumer() method.
  // 2. The transport layer (e.g., src/ipc) when the consumer and
  //    the service don't talk locally but via some IPC mechanism.
  class ConsumerEndpoint {
   public:
    virtual ~ConsumerEndpoint();

    // Enables tracing with the given TraceConfig. The ScopedFile argument is
    // used only when TraceConfig.write_into_file == true.
    virtual void EnableTracing(const TraceConfig&,
                               base::ScopedFile = base::ScopedFile()) = 0;
    virtual void DisableTracing() = 0;

    // Requests all data sources to flush their data immediately and invokes the
    // passed callback once all of them have acked the flush (in which case
    // the callback argument |success| will be true) or |timeout_ms| are elapsed
    // (in which case |success| will be false).
    using FlushCallback = std::function<void(bool /*success*/)>;
    virtual void Flush(uint32_t timeout_ms, FlushCallback) = 0;

    // Tracing data will be delivered invoking Consumer::OnTraceData().
    virtual void ReadBuffers() = 0;

    virtual void FreeBuffers() = 0;
  };  // class ConsumerEndpoint.

  // Implemented in src/core/service_impl.cc .
  static std::unique_ptr<Service> CreateInstance(
      std::unique_ptr<SharedMemory::Factory>,
      base::TaskRunner*);

  virtual ~Service();

  // Connects a Producer instance and obtains a ProducerEndpoint, which is
  // essentially a 1:1 channel between one Producer and the Service.
  // The caller has to guarantee that the passed Producer will be alive as long
  // as the returned ProducerEndpoint is alive.
  // To disconnect just destroy the returned ProducerEndpoint object. It is safe
  // to destroy the Producer once the Producer::OnDisconnect() has been invoked.
  // |uid| is the trusted user id of the producer process, used by the consumers
  // for validating the origin of trace data.
  // |shared_memory_size_hint_bytes| is an optional hint on the size of the
  // shared memory buffer. The service can ignore the hint (e.g., if the hint
  // is unreasonably large).
  // Can return null in the unlikely event that service has too many producers
  // connected.
  virtual std::unique_ptr<ProducerEndpoint> ConnectProducer(
      Producer*,
      uid_t uid,
      const std::string& name,
      size_t shared_memory_size_hint_bytes = 0) = 0;

  // Coonects a Consumer instance and obtains a ConsumerEndpoint, which is
  // essentially a 1:1 channel between one Consumer and the Service.
  // The caller has to guarantee that the passed Consumer will be alive as long
  // as the returned ConsumerEndpoint is alive.
  // To disconnect just destroy the returned ConsumerEndpoint object. It is safe
  // to destroy the Consumer once the Consumer::OnDisconnect() has been invoked.
  virtual std::unique_ptr<ConsumerEndpoint> ConnectConsumer(Consumer*) = 0;
};

}  // namespace perfetto

#endif  // INCLUDE_PERFETTO_TRACING_CORE_SERVICE_H_