trace-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/trace-cpp-api-inlines.h"

Namespaces Index

namespace	micro_os_plus
	The primary namespace for the µOS++ framework. More...
namespace	trace
	Tracing support namespace. More...
namespace	detail
	Implementation details namespace. More...

Classes Index

class	implementation
	Policy class for the production trace instance. More...
class	tracer<T>
	Tracing API bound to a given policy class. More...

Concepts Index

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

Functions Index

void	dump_args (int argc, char *argv[], const char *name="main") noexcept
	Send the argv[] array to the trace output channel. More...
void	flush (void) noexcept
	Flush the trace output channel. More...
void	initialise (void) noexcept
	Initialise the trace output channel. More...
int	printf (const char *format,...) noexcept
	Write a formatted string to the trace output channel. More...
int	putchar (int c) noexcept
	Write the single character to the trace output channel. More...
int	puts (const char *s="") noexcept
	Write the string and a line terminator to the trace output channel. More...
int	vprintf (const char *format, std::va_list arguments) noexcept
	Write a formatted variable arguments list to the trace output channel. More...
ssize_t	write (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 trace-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

6 * for any 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

9 * be 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 <cstdint>

49#include <cstddef>

50#include <cstdarg>

51// #include <cstdlib>

52#include <concepts>

53

54// ----------------------------------------------------------------------------

55

98

99#pragma GCC diagnostic push

100#if defined(__clang__)

101#pragma clang diagnostic ignored "-Wpre-c++17-compat"

102#endif

103

104namespace micro_os_plus::trace

105{

106#pragma GCC diagnostic push

107#if defined(__clang__)

108#pragma clang diagnostic ignored "-Wc++98-compat"

109#pragma clang diagnostic ignored "-Wc++98-c++11-c++14-compat"

110#endif

111

112 // Free functions declarations.

113

128 void

129 initialise (void) noexcept;

130

143 ssize_t

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

145

158 void

159 flush (void) noexcept;

160

161 // --------------------------------------------------------------------------

162

176 int

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

178

192 int

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

194

207 int

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

209

222 int

223 putchar (int c) noexcept;

224

240 void

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

242

243#pragma GCC diagnostic pop

244} // namespace micro_os_plus::trace

245

246// ----------------------------------------------------------------------------

247

248#if defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED)

249

250// ----------------------------------------------------------------------------

251

252namespace micro_os_plus::trace

253{

254#pragma GCC diagnostic push

255#if defined(__clang__)

256#pragma clang diagnostic ignored "-Wc++98-compat"

257#endif

258

259 // --------------------------------------------------------------------------

260

273 namespace detail

274 {

289 class implementation

290 {

291 public:

304 static void

305 initialise (void) noexcept;

306

320 static ssize_t

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

322

337 static void

338 flush (void) noexcept;

339 };

340

341 // ------------------------------------------------------------------------

342

360 template <typename T>

361 concept trace_policy = requires (const void* buf, std::size_t n) {

362 { T::initialise () } noexcept -> std::same_as<void>;

363 { T::write (buf, n) } noexcept -> std::same_as<ssize_t>;

364 { T::flush () } noexcept -> std::same_as<void>;

365 };

366

367 // ------------------------------------------------------------------------

368

390 template <trace_policy T>

391 class tracer

392 {

393 public:

402 tracer () = delete;

403

419 static void

420 initialise (void) noexcept (noexcept (T::initialise ()))

421 {

422 T::initialise ();

423 }

424

439 static ssize_t

440 write (const void* buf,

441 std::size_t nbyte) noexcept (noexcept (T::write (buf, nbyte)))

442 {

443 return T::write (buf, nbyte);

444 }

445

463 static void

464 flush (void) noexcept (noexcept (T::flush ()))

465 {

466 T::flush ();

467 }

468

469 // ----------------------------------------------------------------------

470

485 static int

486 printf (const char* format, ...) noexcept

487 __attribute__ ((format (printf, 1, 2)));

488

506 static int

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

508

523 static int

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

525

537 static int

538 putchar (int c) noexcept;

539

557 static void

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

559 };

560

561 // ------------------------------------------------------------------------

562 // Suppress implicit instantiation of the tracer member function bodies

563 // in every TU that includes this header. The explicit instantiations in

564 // trace.cpp are the sole ODR-defining instances.

565 // ------------------------------------------------------------------------

566

567#pragma GCC diagnostic push

568#if defined(__clang__)

569#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"

570#endif

571

572 extern template class tracer<implementation>;

573

574#pragma GCC diagnostic pop

575 } // namespace detail

576

577#pragma GCC diagnostic pop

578} // namespace micro_os_plus::trace

579

580// ----------------------------------------------------------------------------

581

582#endif // defined(MICRO_OS_PLUS_DIAG_TRACE_ENABLED)

583

584// ----------------------------------------------------------------------------

585

586#pragma GCC diagnostic pop

587

588// ----------------------------------------------------------------------------

589

590#endif // defined(__cplusplus)

591

592// ============================================================================

593// Templates, inlines & constexpr implementations.

594

595#include "inlines/trace-cpp-api-inlines.h"

596

597// ----------------------------------------------------------------------------

598

599#endif // MICRO_OS_PLUS_DIAG_TRACE_CPP_API_H_

600

601// ----------------------------------------------------------------------------

---

Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.17.0.