cpp-api.h

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2015-2026 Liviu Ionescu. All rights reserved.
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose is hereby granted, under the terms of the MIT license.
 *
 * If a copy of the license was not distributed with this file, it can be
 * obtained from https://opensource.org/licenses/mit.
 */
 
// ----------------------------------------------------------------------------

 
// ----------------------------------------------------------------------------
 
#if !defined(MICRO_OS_PLUS_DIAG_TRACE_H_)
#error "Do not include this file directly; use micro-os-plus/diag/trace.h."
#endif // MICRO_OS_PLUS_DIAG_TRACE_H_
 
// ----------------------------------------------------------------------------
 
#ifndef MICRO_OS_PLUS_DIAG_TRACE_CPP_API_H_
#define MICRO_OS_PLUS_DIAG_TRACE_CPP_API_H_
 
// ----------------------------------------------------------------------------
 
#if defined(__cplusplus)
 
// ----------------------------------------------------------------------------
 
#include <sys/types.h>
 
#include <cstddef>
#include <cstdarg>
#include <concepts>
 
// ----------------------------------------------------------------------------

 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wpre-c++17-compat"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
namespace micro_os_plus::trace
{
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#pragma clang diagnostic ignored "-Wc++98-c++11-c++14-compat"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
  // Free functions declarations.

  void
  initialise (void) noexcept;

  ssize_t
  write (const void* buf, std::size_t nbyte) noexcept;

  void
  flush (void) noexcept;
 
  // --------------------------------------------------------------------------

  int
  printf (const char* format, ...) noexcept;

  int
  vprintf (const char* format, std::va_list arguments) noexcept;

  int
  puts (const char* s = "") noexcept;

  int
  putchar (int c) noexcept;

  void
  dump_args (int argc, char* argv[], const char* name = "main") noexcept;
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
} // namespace micro_os_plus::trace
 
// ----------------------------------------------------------------------------
 
#if defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED)
 
// ----------------------------------------------------------------------------
 
namespace micro_os_plus::trace
{
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
  // --------------------------------------------------------------------------

  namespace detail
  {
    class implementation
    {
    public:
      static void
      initialise (void) noexcept;

      static ssize_t
      write (const void* buf, std::size_t nbyte) noexcept;

      static void
      flush (void) noexcept;
    };
 
    // ------------------------------------------------------------------------

    template <typename T>
    concept trace_policy = requires (const void* buf, std::size_t n) {
      { T::initialise () } noexcept -> std::same_as<void>;
      { T::write (buf, n) } noexcept -> std::same_as<ssize_t>;
      { T::flush () } noexcept -> std::same_as<void>;
    };
 
    // ------------------------------------------------------------------------

    template <trace_policy T>
    class tracer
    {
    public:
      tracer () = delete;

      static void
      initialise (void) noexcept
      {
        T::initialise ();
      }

      static ssize_t
      write (const void* buf, std::size_t nbyte) noexcept
      {
        return T::write (buf, nbyte);
      }

      static void
      flush (void) noexcept
      {
        T::flush ();
      }
 
      // ----------------------------------------------------------------------

      static int
      printf (const char* format, ...) noexcept
          __attribute__ ((format (printf, 1, 2)));

      static int
      vprintf (const char* format, std::va_list arguments) noexcept;

      static int
      puts (const char* s = "") noexcept;

      static int
      putchar (int c) noexcept;

      static void
      dump_args (int argc, char* argv[], const char* name = "main") noexcept;
    };
 
    // ------------------------------------------------------------------------
    // Suppress implicit instantiation of the tracer member function bodies
    // in every TU that includes this header. The explicit instantiations in
    // trace.cpp are the sole ODR-defining instances.
    // ------------------------------------------------------------------------
 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
    extern template class tracer<implementation>;
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
  } // namespace detail
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
} // namespace micro_os_plus::trace
 
// ----------------------------------------------------------------------------
 
#endif // defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED)
 
// ----------------------------------------------------------------------------
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
 
// ----------------------------------------------------------------------------
 
#endif // defined(__cplusplus)
 
// ============================================================================
// Templates, inlines & constexpr implementations.
 
#include "inlines/cpp-api-inlines.h"
 
// ----------------------------------------------------------------------------
 
#endif // MICRO_OS_PLUS_DIAG_TRACE_CPP_API_H_
 
// ----------------------------------------------------------------------------