// Copyright 2017 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

//
// Trace handlers manage the configuration, lifecycle, and external communication
// of the trace engine.
//
// See <trace-engine/handler.h> for the C API and more detailed documentation.
//

#ifndef ZIRCON_SYSTEM_ULIB_LIB_TRACE_PROVIDER_HANDLER_H_
#define ZIRCON_SYSTEM_ULIB_LIB_TRACE_PROVIDER_HANDLER_H_

#include <lib/trace-engine/handler.h>

#ifdef __cplusplus

namespace trace {

// Implements |trace_handler_t|.
// Make sure the trace has fully stopped before destroying the handler object.
class TraceHandler : public trace_handler_t {
 public:
  TraceHandler();
  virtual ~TraceHandler();

  // Called by the trace engine to ask whether the specified category is enabled.
  //
  // This method may be called frequently so it must be efficiently implemented.
  // Clients may cache the results while a trace is running; dynamic changes
  // to the enabled categories may go unnoticed until the next trace.
  //
  // |category| is the name of the category.
  //
  // Called by instrumentation on any thread.  Must be thread-safe.
  virtual bool IsCategoryEnabled(const char* category) { return true; }

  // Called by the trace engine to indicate it has completed startup.
  virtual void TraceStarted() {}

  // Called by the trace engine when tracing has stopped.
  //
  // The trace collection status is |ZX_OK| if trace collection was successful.
  // An error indicates that the trace data may be inaccurate or incomplete.
  //
  // |disposition| is |ZX_OK| if tracing stopped normally, otherwise indicates
  // that tracing was aborted due to an error. If records were dropped (due
  // to the trace buffer being full) then |disposition| is |ZX_ERR_NO_MEMORY|.
  //
  // Called on an asynchronous dispatch thread.
  virtual void TraceStopped(zx_status_t disposition) {}

  // Called by the trace engine when tracing has terminated.
  virtual void TraceTerminated() {}

  // Called by the trace engine in streaming mode to indicate a buffer is full.
  // This is only used in streaming mode where double-buffering is used.
  // |wrapped_count| is the number of times writing to the buffer has
  // switched from one buffer to the other.
  // |durable_buffer_offset| is the offset into the durable buffer when the
  // buffer filled. It is provided so that TraceManager can save the data
  // thus far written to the durable buffer.
  virtual void NotifyBufferFull(uint32_t wrapped_count, uint64_t durable_buffer_offset) {}

  // Called by the trace engine to send an alert.
  virtual void SendAlert(const char* alert_name) {}

 private:
  static bool CallIsCategoryEnabled(trace_handler_t* handler, const char* category);
  static void CallTraceStarted(trace_handler_t* handler);
  static void CallTraceStopped(trace_handler_t* handler, zx_status_t disposition);
  static void CallTraceTerminated(trace_handler_t* handler);
  static void CallNotifyBufferFull(trace_handler_t* handler, uint32_t wrapped_count,
                                   uint64_t durable_buffer_offset);
  static void CallSendAlert(trace_handler_t* handler, const char* alert_name);

  static const trace_handler_ops_t kOps;
};

}  // namespace trace

#endif  // __cplusplus

#endif  // ZIRCON_SYSTEM_ULIB_LIB_TRACE_PROVIDER_HANDLER_H_