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(noexcept(T::flush()))
	Flush the trace output channel.
static void	initialise (void) noexcept(noexcept(T::initialise()))
	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(noexcept(T::write(buf, nbyte)))
	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 391 of file trace-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 193 of file trace-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. The noexcept specification mirrors that of the policy method.

Definition at line 464 of file trace-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. The noexcept specification mirrors that of the policy method.

Definition at line 420 of file trace-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.

Definition at line 79 of file trace-cpp-api-inlines.h.

    {
      std::va_list arguments;
      va_start (arguments, format);
 
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
      int ret = vprintf (format, arguments);
#pragma GCC diagnostic pop
 
      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 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 173 of file trace-cpp-api-inlines.h.

    {
      char ch = static_cast<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 135 of file trace-cpp-api-inlines.h.

    {
#pragma GCC diagnostic push
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
      ssize_t ret = write (s, std::strlen (s));
#pragma GCC diagnostic pop
      if (ret >= 0)
        {
          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)
        {
#pragma GCC diagnostic push
#if defined(__GNUC__) && !defined(__clang__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
          // Cast required on 64-bit.
          return static_cast<int> (ret);
#pragma GCC diagnostic pop
        }
      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. Typically called by printf().

Definition at line 97 of file trace-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).
 
      // Print to the local buffer
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wformat-nonliteral"
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"
#endif
      ssize_t ret = ::vsnprintf (buf, sizeof (buf), format, arguments);
#pragma GCC diagnostic pop
      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))));
        }
#pragma GCC diagnostic push
#if defined(__GNUC__) && !defined(__clang__)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
      // Cast required on 64-bit.
      return static_cast<int> (ret);
#pragma GCC diagnostic pop
    }

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. The noexcept specification mirrors that of the policy method.

Definition at line 440 of file trace-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:

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