Skip to main content

cpp-api.h File

C++ header file with the declarations for the C++ trace API. More...

Included Headers​

#include <sys/types.h> #include <cstddef> #include <cstdarg> #include <concepts> #include "inlines/cpp-api-inlines.h"

Namespaces Index​

namespacemicro_os_plus

The primary namespace for the µOS++ framework. More...

namespacetrace

Tracing support namespace. More...

namespacedetail

Implementation details namespace. More...

Classes Index​

classimplementation

Policy class for the production trace instance. More...

classtracer<T>

Tracing API bound to a given policy class. More...

Concepts Index​

concepttrace_policy

Concept constraining the policy class T used by tracer<T>. More...

Functions Index​

voiddump_args (int argc, char *argv[], const char *name="main") noexcept

Send the argv[] array to the trace output channel. More...

voidflush (void) noexcept

Flush the trace output channel. More...

voidinitialise (void) noexcept

Initialise the trace output channel. More...

intprintf (const char *format,...) noexcept

Write a formatted string to the trace output channel. More...

intputchar (int c) noexcept

Write the single character to the trace output channel. More...

intputs (const char *s="") noexcept

Write the string and a line terminator to the trace output channel. More...

intvprintf (const char *format, std::va_list arguments) noexcept

Write a formatted variable arguments list to the trace output channel. More...

ssize_twrite (const void *buf, std::size_t nbyte) noexcept

Write the given number of bytes to the trace output channel. More...

Description​

C++ header file with the declarations for the C++ trace API.

Declarations for the tracer class template and the trace_policy concept.

Inline method definitions are located in cpp-api-inlines.h, included at the bottom of this file. This file is included by "micro-os-plus/diag/trace.h", which should be used instead of including this file directly.

File Listing​

The file content with the documentation metadata removed is:

1/*
2 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
3 * Copyright (c) 2015-2026 Liviu Ionescu. All rights reserved.
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose is hereby granted, under the terms of the MIT license.
7 *
8 * If a copy of the license was not distributed with this file, it can be
9 * obtained from https://opensource.org/licenses/mit.
10 */
11
12// ----------------------------------------------------------------------------
13
28
29// ----------------------------------------------------------------------------
30
31#if !defined(MICRO_OS_PLUS_DIAG_TRACE_H_)
32#error "Do not include this file directly; use micro-os-plus/diag/trace.h."
33#endif // MICRO_OS_PLUS_DIAG_TRACE_H_
34
35// ----------------------------------------------------------------------------
36
37#ifndef MICRO_OS_PLUS_DIAG_TRACE_CPP_API_H_
38#define MICRO_OS_PLUS_DIAG_TRACE_CPP_API_H_
39
40// ----------------------------------------------------------------------------
41
42#if defined(__cplusplus)
43
44// ----------------------------------------------------------------------------
45
46#include <sys/types.h>
47
48#include <cstddef>
49#include <cstdarg>
50#include <concepts>
51
52// ----------------------------------------------------------------------------
53
96
97#if defined(__GNUC__)
98#pragma GCC diagnostic push
99
100#if defined(__clang__)
101#pragma clang diagnostic ignored "-Wpre-c++17-compat"
102#endif // defined(__clang__)
103#endif // defined(__GNUC__)
104
105namespace micro_os_plus::trace
106{
107#if defined(__GNUC__)
108#pragma GCC diagnostic push
109
110#if defined(__clang__)
111#pragma clang diagnostic ignored "-Wc++98-compat"
112#pragma clang diagnostic ignored "-Wc++98-c++11-c++14-compat"
113#endif // defined(__clang__)
114#endif // defined(__GNUC__)
115
116 // Free functions declarations.
117
132 void
133 initialise (void) noexcept;
134
147 ssize_t
148 write (const void* buf, std::size_t nbyte) noexcept;
149
162 void
163 flush (void) noexcept;
164
165 // --------------------------------------------------------------------------
166
181 int
182 printf (const char* format, ...) noexcept;
183
199 int
200 vprintf (const char* format, std::va_list arguments) noexcept;
201
214 int
215 puts (const char* s = "") noexcept;
216
229 int
230 putchar (int c) noexcept;
231
247 void
248 dump_args (int argc, char* argv[], const char* name = "main") noexcept;
249
250#if defined(__GNUC__)
251#pragma GCC diagnostic pop
252#endif // defined(__GNUC__)
253} // namespace micro_os_plus::trace
254
255// ----------------------------------------------------------------------------
256
257#if defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED)
258
259// ----------------------------------------------------------------------------
260
261namespace micro_os_plus::trace
262{
263#if defined(__GNUC__)
264#pragma GCC diagnostic push
265
266#if defined(__clang__)
267#pragma clang diagnostic ignored "-Wc++98-compat"
268#endif // defined(__clang__)
269#endif // defined(__GNUC__)
270
271 // --------------------------------------------------------------------------
272
285 namespace detail
286 {
301 class implementation
302 {
303 public:
316 static void
317 initialise (void) noexcept;
318
332 static ssize_t
333 write (const void* buf, std::size_t nbyte) noexcept;
334
349 static void
350 flush (void) noexcept;
351 };
352
353 // ------------------------------------------------------------------------
354
372 template <typename T>
373 concept trace_policy = requires (const void* buf, std::size_t n) {
374 { T::initialise () } noexcept -> std::same_as<void>;
375 { T::write (buf, n) } noexcept -> std::same_as<ssize_t>;
376 { T::flush () } noexcept -> std::same_as<void>;
377 };
378
379 // ------------------------------------------------------------------------
380
402 template <trace_policy T>
403 class tracer
404 {
405 public:
414 tracer () = delete;
415
431 static void
432 initialise (void) noexcept
433 {
434 T::initialise ();
435 }
436
452 static ssize_t
453 write (const void* buf, std::size_t nbyte) noexcept
454 {
455 return T::write (buf, nbyte);
456 }
457
476 static void
477 flush (void) noexcept
478 {
479 T::flush ();
480 }
481
482 // ----------------------------------------------------------------------
483
499 static int
500 printf (const char* format, ...) noexcept
501 __attribute__ ((format (printf, 1, 2)));
502
521 static int
522 vprintf (const char* format, std::va_list arguments) noexcept;
523
538 static int
539 puts (const char* s = "") noexcept;
540
552 static int
553 putchar (int c) noexcept;
554
572 static void
573 dump_args (int argc, char* argv[], const char* name = "main") noexcept;
574 };
575
576 // ------------------------------------------------------------------------
577 // Suppress implicit instantiation of the tracer member function bodies
578 // in every TU that includes this header. The explicit instantiations in
579 // trace.cpp are the sole ODR-defining instances.
580 // ------------------------------------------------------------------------
581
582#if defined(__GNUC__)
583#pragma GCC diagnostic push
584
585#if defined(__clang__)
586#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
587#endif // defined(__clang__)
588#endif // defined(__GNUC__)
589
590 extern template class tracer<implementation>;
591
592#if defined(__GNUC__)
593#pragma GCC diagnostic pop
594#endif // defined(__GNUC__)
595 } // namespace detail
596
597#if defined(__GNUC__)
598#pragma GCC diagnostic pop
599#endif // defined(__GNUC__)
600} // namespace micro_os_plus::trace
601
602// ----------------------------------------------------------------------------
603
604#endif // defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED)
605
606// ----------------------------------------------------------------------------
607
608#if defined(__GNUC__)
609#pragma GCC diagnostic pop
610#endif // defined(__GNUC__)
611
612// ----------------------------------------------------------------------------
613
614#endif // defined(__cplusplus)
615
616// ============================================================================
617// Templates, inlines & constexpr implementations.
618
619#include "inlines/cpp-api-inlines.h"
620
621// ----------------------------------------------------------------------------
622
623#endif // MICRO_OS_PLUS_DIAG_TRACE_CPP_API_H_
624
625// ----------------------------------------------------------------------------

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.17.0.

Last updated on