`tracer` Class Template

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

Declaration

template <trace_policy T>
class micro_os_plus::trace::detail::tracer<T> { ... }

Included Headers

Public Constructors Index

template <trace_policy T>
tracer ()=delete
	Deleted default constructor. More...

Public Static Functions Index

template <trace_policy T>
static void	dump_args (int argc, char argv[], const char name="main") noexcept
	Send the argv[] array to the trace output channel. More...

template <trace_policy T>
static void	flush (void)
	Flush the trace output channel. More...

template <trace_policy T>
static void	initialise (void)
	Initialise the trace output channel. More...

template <trace_policy T>
static int	printf (const char *format,...) noexcept
	Write a formatted string to the trace output channel. More...

template <trace_policy T>
static int	putchar (int c) noexcept
	Write the single character to the trace output channel. More...

template <trace_policy T>
static int	puts (const char *s="") noexcept
	Write the string and a line terminator to the trace output channel. More...

template <trace_policy T>
static int	vprintf (const char *format, std::va_list arguments) noexcept
	Write a formatted variable arguments list to the trace output channel. More...

template <trace_policy T>
static ssize_t	write (const void *buf, std::size_t nbyte)
	Write the given number of bytes to the trace output channel. More...

Description

Tracing API bound to a given policy class.

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.

Public Constructors

tracer()

template <trace_policy T>

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

delete

Deleted default constructor.

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.

Definition at line 402 of file trace-cpp-api.h.

Public Static Functions

dump_args()

template <trace_policy T>

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

noexcept static

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

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.

Declaration at line 558 of file trace-cpp-api.h, definition at line 193 of file trace-cpp-api-inlines.h.

193 tracer<T>::dump_args (int argc, char* argv[], const char* name) noexcept

194 {

195 printf ("%s(argc=%d, argv=[", name, argc);

196 for (int i = 0; i < argc; ++i)

197 {

198 if (i != 0)

199 {

200 printf (", ");

201 }

202 printf ("\"%s\"", argv[i]);

203 }

204 printf ("])\n");

205 }

Reference 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)

inline noexcept static

Flush the trace output channel.

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.

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

465 {

466 T::flush ();

467 }

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)

inline noexcept static

Initialise the trace output channel.

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.

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

421 {

422 T::initialise ();

423 }

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, ...)

noexcept static

Write a formatted string to the trace output channel.

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.

Declaration at line 486 of file trace-cpp-api.h, definition at line 79 of file trace-cpp-api-inlines.h.

79 tracer<T>::printf (const char* format, ...) noexcept

80 {

81 std::va_list arguments;

82 va_start (arguments, format);

84#pragma GCC diagnostic push

85#if defined(__clang__)

86#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

87#endif

88 int ret = vprintf (format, arguments);

89#pragma GCC diagnostic pop

91 va_end (arguments);

92 return ret;

93 }

Reference micro_os_plus::trace::vprintf.

putchar()

template <trace_policy T>

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

noexcept static

Write the single character to the trace output channel.

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.

Declaration at line 538 of file trace-cpp-api.h, definition at line 173 of file trace-cpp-api-inlines.h.

173 tracer<T>::putchar (int c) noexcept

174 {

175 char ch = static_cast<char> (c);

176 ssize_t ret = write (&ch, 1);

177 if (ret > 0)

178 {

179 return c;

180 }

181 else

182 {

183 return EOF;

184 }

185 }

Reference 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="")

noexcept static

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

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.

Declaration at line 524 of file trace-cpp-api.h, definition at line 135 of file trace-cpp-api-inlines.h.

135 tracer<T>::puts (const char* s) noexcept

136 {

137#pragma GCC diagnostic push

138#if defined(__clang__)

139#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

140#endif

141 ssize_t ret = write (s, std::strlen (s));

142#pragma GCC diagnostic pop

143 if (ret >= 0)

144 {

145 ssize_t ret2 = write ("\n", 1); // Add a line terminator

146 if (ret2 < 0)

147 {

148 ret = ret2; // Propagate the error.

149 }

150 else

151 {

152 ret += ret2; // Return total bytes written.

153 }

154 }

155 if (ret > 0)

156 {

157#pragma GCC diagnostic push

158#if defined(__GNUC__) && !defined(__clang__)

159#pragma GCC diagnostic ignored "-Wuseless-cast"

160#endif

161 // Cast required on 64-bit.

162 return static_cast<int> (ret);

163#pragma GCC diagnostic pop

164 }

165 else

166 {

167 return EOF;

168 }

169 }

Reference 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)

noexcept static

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

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().

Declaration at line 507 of file trace-cpp-api.h, definition at line 97 of file trace-cpp-api-inlines.h.

97 tracer<T>::vprintf (const char* format, std::va_list arguments) noexcept

98 {

99 // Caution: allocated on the stack!

100 char buf[MICRO_OS_PLUS_DIAG_TRACE_PRINTF_BUFFER_ARRAY_SIZE_INTEGER];

101

102 // TODO: possibly rewrite it to no longer use newlib,

103 // (although the nano version is no longer very heavy).

104

105 // Print to the local buffer

106#pragma GCC diagnostic push

107#pragma GCC diagnostic ignored "-Wformat-nonliteral"

108#if defined(__clang__)

109#pragma clang diagnostic ignored "-Wunsafe-buffer-usage-in-libc-call"

110#endif

111 ssize_t ret = ::vsnprintf (buf, sizeof (buf), format, arguments);

112#pragma GCC diagnostic pop

113 if (ret > 0)

114 {

115 // Clamp to actual buffer size if output was truncated.

116 // Note: on truncation the return value becomes the byte count

117 // written to the channel, not the total length vsnprintf

118 // computed. Callers cannot use the return value to detect

119 // truncation.

120 ret = write (buf,

121 static_cast<size_t> (std::min (

122 ret, static_cast<ssize_t> (sizeof (buf) - 1))));

123 }

124#pragma GCC diagnostic push

125#if defined(__GNUC__) && !defined(__clang__)

126#pragma GCC diagnostic ignored "-Wuseless-cast"

127#endif

128 // Cast required on 64-bit.

129 return static_cast<int> (ret);

130#pragma GCC diagnostic pop

131 }

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)

inline noexcept static

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

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.

440 write (const void* buf,

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

442 {

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

444 }

Referenced by micro_os_plus_trace_write and micro_os_plus::trace::write.

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

Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.17.0.

Declaration​

Included Headers​

Public Constructors Index​

Public Static Functions Index​

Description​

Public Constructors​

tracer()​

Public Static Functions​

dump_args()​

flush()​

initialise()​

printf()​

putchar()​

puts()​

vprintf()​

write()​

Declaration

Included Headers

Public Constructors Index

Public Static Functions Index

Description

Public Constructors

tracer()

Public Static Functions

dump_args()

flush()

initialise()

printf()

putchar()

puts()

vprintf()

write()