micro_os_plus::trace::detail::tracer< T > Class Template Reference

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

#include "micro-os-plus/diag/trace.h"

Public Member Functions
	tracer ()=delete
	Deleted default constructor.

Static Public Member Functions
static void	dump_args (int argc, char *argv[], const char *name="main") noexcept
	Send the argv[] array to the trace output channel.
static void	flush (void) noexcept
	Flush the trace output channel.
static void	initialise (void) noexcept
	Initialise the trace output channel.
static int	printf (const char *format,...) noexcept
	Write a formatted string to the trace output channel.
static int	putchar (int c) noexcept
	Write the single character to the trace output channel.
static int	puts (const char *s="") noexcept
	Write the string and a line terminator to the trace output channel.
static int	vprintf (const char *format, std::va_list arguments) noexcept
	Write a formatted variable arguments list to the trace output channel.
static ssize_t	write (const void *buf, std::size_t nbyte) noexcept
	Write the given number of bytes to the trace output channel.

Detailed Description

template<trace_policy T>
class micro_os_plus::trace::detail::tracer< T >

Template Parameters

T	Policy class providing the static initialise(), write(), and flush() primitives (e.g. micro_os_plus::trace::detail::implementation).

All methods are static; tracer is never instantiated as an object. Each distinct T produces an independent set of methods with no shared state, so tracer<implementation> (or any further user-defined policy class) can coexist in the same translation unit and binary.

The main reason for using a class template rather than a namespace is that it allows the policy class to be a template parameter, so that multiple independent instances can coexist in the same binary, each bound to a different policy class. This is used in testing, where a testing_implementation policy class is defined to capture the output for verification.

Definition at line 403 of file cpp-api.h.

Constructor & Destructor Documentation

tracer()

template<trace_policy T>

micro_os_plus::trace::detail::tracer< T >::tracer ( )

delete

tracer is a purely static utility class; all methods are static and no instance is ever created. The default constructor is explicitly deleted to enforce this intent and prevent accidental instantiation.

Member Function Documentation

dump_args()

template<trace_policy T>

void micro_os_plus::trace::detail::tracer< T >::dump_args ( int argc, char * argv[], const char * name = "main" )

staticnoexcept

Parameters

argc	The number of argv[] strings.
argv	An array of pointers to argument strings.
name	A null terminated string used as the function name prefix (default: "main").

Returns

Nothing.

Formats and writes the argument list in the form name(argc=N, argv=["arg0", "arg1", ...]), followed by a newline. Intended to be called at the start of main() to record the process arguments in the trace output. Each argument string is quoted; no escaping is applied to the string content.

Definition at line 210 of file cpp-api-inlines.h.

    {
      printf ("%s(argc=%d, argv=[", name, argc);
      for (int i = 0; i < argc; ++i)
        {
          if (i != 0)
            {
              printf (", ");
            }
          printf ("\"%s\"", argv[i]);
        }
      printf ("])\n");
    }

References micro_os_plus::trace::printf().

Referenced by micro_os_plus::trace::dump_args(), and micro_os_plus_trace_dump_args().

flush()

template<trace_policy T>

void micro_os_plus::trace::detail::tracer< T >::flush ( void )

inlinestaticnoexcept

Parameters

None.

Returns

Nothing.

Delegates unconditionally to T::flush().

For buffered output channels, the policy method must drain any internally buffered data to the output device. For unbuffered or character-mode channels (e.g. ITM), the policy method body can be left empty. Unconditionally noexcept, since the trace_policy concept already requires T::flush() to be noexcept.

Definition at line 477 of file cpp-api.h.

      {
        T::flush ();
      }

Referenced by micro_os_plus::trace::flush(), and micro_os_plus_trace_flush().

initialise()

template<trace_policy T>

void micro_os_plus::trace::detail::tracer< T >::initialise ( void )

inlinestaticnoexcept

Parameters

None.

Returns

Nothing.

Delegates unconditionally to T::initialise().

Called during startup, as early as possible, to enable the trace channel. Unconditionally noexcept, since the trace_policy concept already requires T::initialise() to be noexcept.

Definition at line 432 of file cpp-api.h.

      {
        T::initialise ();
      }

Referenced by micro_os_plus::trace::initialise(), and micro_os_plus_trace_initialise().

printf()

template<trace_policy T>

int micro_os_plus::trace::detail::tracer< T >::printf ( const char * format, ... )

staticnoexcept

Parameters

format	A null terminated string with the format.
...	Additional arguments matching the format specifiers.

Returns

The number of bytes written, or -1 if an error occurred.

Formatting is performed into a fixed-size stack buffer of MICRO_OS_PLUS_DIAG_TRACE_PRINTF_BUFFER_ARRAY_SIZE_INTEGER bytes (default: 200). Output that exceeds this limit is silently truncated before being passed to write(). The return value reflects the bytes actually written, not the number that the format string would have produced; it cannot be used to detect whether truncation occurred.

Definition at line 76 of file cpp-api-inlines.h.

    {
      std::va_list arguments;
      va_start (arguments, format);
 
      int ret = vprintf (format, arguments);
 
      va_end (arguments);
      return ret;
    }

References micro_os_plus::trace::vprintf().

putchar()

template<trace_policy T>

int micro_os_plus::trace::detail::tracer< T >::putchar ( int c )

staticnoexcept

Parameters

c	A single byte character, passed as an int.

Returns

The written character as an int, or EOF (-1) if an error occurred.

Converts c to unsigned char and passes it as a one-byte buffer to write(). On success, returns the original value of c; on failure, returns EOF.

Definition at line 186 of file cpp-api-inlines.h.

    {
      auto ch = static_cast<unsigned char> (c);
      ssize_t ret = write (&ch, 1);
      if (ret > 0)
        {
          return c;
        }
      else
        {
          return EOF;
        }
    }

References micro_os_plus::trace::write().

Referenced by micro_os_plus_trace_putchar(), and micro_os_plus::trace::putchar().

puts()

template<trace_policy T>

int micro_os_plus::trace::detail::tracer< T >::puts ( const char * s = "" )

staticnoexcept

Parameters

s	A null terminated string (default: empty string).

Returns

The total number of bytes written (string + newline), or EOF (-1) if an error occurred.

Writes the characters of s followed by a single newline character ('\n'). Unlike the standard C puts(), this function returns the total byte count written. If writing the newline fails after the string has been written successfully, EOF is returned.

Definition at line 141 of file cpp-api-inlines.h.

    {
      std::size_t len = std::strlen (s);
      ssize_t ret = write (s, len);
      // Only append the line terminator if the string was written in
      // full; a partial write (including a zero-byte write, which is
      // not itself an error) must not be followed by a bare newline.
      if (ret >= 0 && static_cast<std::size_t> (ret) == len)
        {
          ssize_t ret2 = write ("\n", 1); // Add a line terminator
          if (ret2 < 0)
            {
              ret = ret2; // Propagate the error.
            }
          else
            {
              ret += ret2; // Return total bytes written.
            }
        }
      if (ret > 0)
        {
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
          // Cast required on 64-bit.
          return static_cast<int> (ret);
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
        }
      else
        {
          return EOF;
        }
    }

References micro_os_plus::trace::write().

Referenced by micro_os_plus_trace_puts(), and micro_os_plus::trace::puts().

vprintf()

template<trace_policy T>

int micro_os_plus::trace::detail::tracer< T >::vprintf ( const char * format, std::va_list arguments )

staticnoexcept

Parameters

format	A null terminated string with the format.
arguments	A variable arguments list.

Returns

The number of bytes written to the output channel, or -1 if an error occurred.

Equivalent to printf(), but accepts a std::va_list instead of a variadic argument list. Subject to the same fixed-size stack buffer constraint. When the formatted output exceeds the buffer size, the text is truncated silently; the return value then reflects the bytes actually written to the channel, not the total length that vsnprintf would have produced, and cannot be used to detect whether truncation occurred. Typically called by printf().

Definition at line 89 of file cpp-api-inlines.h.

    {
      // Caution: allocated on the stack!
      char buf[MICRO_OS_PLUS_DIAG_TRACE_PRINTF_BUFFER_ARRAY_SIZE_INTEGER];
 
      // TODO: possibly rewrite it to no longer use newlib,
      // (although the nano version is no longer very heavy).
 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#pragma GCC diagnostic ignored "-Wformat-nonliteral"
#endif // defined(__GNUC__)
 
      // Print to the local buffer
      ssize_t ret = ::vsnprintf (buf, sizeof (buf), format, arguments);
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
 
      if (ret > 0)
        {
          // Clamp to actual buffer size if output was truncated.
          // Note: on truncation the return value becomes the byte count
          // written to the channel, not the total length vsnprintf
          // computed. Callers cannot use the return value to detect
          // truncation.
          ret = write (buf,
                       static_cast<size_t> (std::min (
                           ret, static_cast<ssize_t> (sizeof (buf) - 1))));
        }
 
#if defined(__GNUC__)
#pragma GCC diagnostic push
 
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif // defined(__clang__)
#endif // defined(__GNUC__)
 
      // Cast required on 64-bit.
      return static_cast<int> (ret);
 
#if defined(__GNUC__)
#pragma GCC diagnostic pop
#endif // defined(__GNUC__)
    }

References MICRO_OS_PLUS_DIAG_TRACE_PRINTF_BUFFER_ARRAY_SIZE_INTEGER, and micro_os_plus::trace::write().

Referenced by micro_os_plus_trace_printf(), micro_os_plus_trace_vprintf(), micro_os_plus::trace::printf(), and micro_os_plus::trace::vprintf().

write()

template<trace_policy T>

ssize_t micro_os_plus::trace::detail::tracer< T >::write ( const void * buf, std::size_t nbyte )

inlinestaticnoexcept

Parameters

buf	An array of bytes.
nbyte	The number of bytes in the array.

Returns

The number of bytes actually written, or -1 if error.

Delegates unconditionally to T::write().

The return value must reflect the number of bytes actually transferred; a return value of -1 signals an error. Unconditionally noexcept, since the trace_policy concept already requires T::write() to be noexcept.

Definition at line 453 of file cpp-api.h.

      {
        return T::write (buf, nbyte);
      }

Referenced by micro_os_plus_trace_write(), and micro_os_plus::trace::write().

---

The documentation for this class was generated from the following files:

• cpp-api.h
• cpp-api-inlines.h