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

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

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) noexcept
	Flush the trace output channel. More...
template <trace_policy T>
static void	initialise (void) noexcept
	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) noexcept
	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 403 of file 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 414 of file 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 573 of file cpp-api.h, definition at line 210 of file cpp-api-inlines.h.

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

211 {

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

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

214 {

215 if (i != 0)

216 {

217 printf (", ");

218 }

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

220 }

221 printf ("])\n");

222 }

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. Unconditionally noexcept, since the trace_policy concept already requires T::flush() to be noexcept.

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

477 flush (void) noexcept

478 {

479 T::flush ();

480 }

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. Unconditionally noexcept, since the trace_policy concept already requires T::initialise() to be noexcept.

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

432 initialise (void) noexcept

433 {

434 T::initialise ();

435 }

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; it cannot be used to detect whether truncation occurred.

Declaration at line 500 of file cpp-api.h, definition at line 76 of file cpp-api-inlines.h.

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

77 {

78 std::va_list arguments;

79 va_start (arguments, format);

80

81 int ret = vprintf (format, arguments);

82

83 va_end (arguments);

84 return ret;

85 }

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 unsigned 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 553 of file cpp-api.h, definition at line 186 of file cpp-api-inlines.h.

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

187 {

188 auto ch = static_cast<unsigned char> (c);

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

190 if (ret > 0)

191 {

192 return c;

193 }

194 else

195 {

196 return EOF;

197 }

198 }

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 539 of file cpp-api.h, definition at line 141 of file cpp-api-inlines.h.

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

142 {

143 std::size_t len = std::strlen (s);

144 ssize_t ret = write (s, len);

145 // Only append the line terminator if the string was written in

146 // full; a partial write (including a zero-byte write, which is

147 // not itself an error) must not be followed by a bare newline.

148 if (ret >= 0 && static_cast<std::size_t> (ret) == len)

149 {

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

151 if (ret2 < 0)

152 {

153 ret = ret2; // Propagate the error.

154 }

155 else

156 {

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

158 }

159 }

160 if (ret > 0)

161 {

162#if defined(__GNUC__)

163#pragma GCC diagnostic push

164

165#if defined(__clang__)

166#elif defined(__GNUC__)

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

168#endif // defined(__clang__)

169#endif // defined(__GNUC__)

170

171 // Cast required on 64-bit.

172 return static_cast<int> (ret);

173

174#if defined(__GNUC__)

175#pragma GCC diagnostic pop

176#endif // defined(__GNUC__)

177 }

178 else

179 {

180 return EOF;

181 }

182 }

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, and cannot be used to detect whether truncation occurred. Typically called by printf().

Declaration at line 522 of file cpp-api.h, definition at line 89 of file cpp-api-inlines.h.

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

90 {

91 // Caution: allocated on the stack!

92 char buf[MICRO_OS_PLUS_DIAG_TRACE_PRINTF_BUFFER_ARRAY_SIZE_INTEGER];

93

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

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

96

97#if defined(__GNUC__)

98#pragma GCC diagnostic push

99

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

101#endif // defined(__GNUC__)

102

103 // Print to the local buffer

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

105

106#if defined(__GNUC__)

107#pragma GCC diagnostic pop

108#endif // defined(__GNUC__)

109

110 if (ret > 0)

111 {

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

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

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

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

116 // truncation.

117 ret = write (buf,

118 static_cast<size_t> (std::min (

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

120 }

121

122#if defined(__GNUC__)

123#pragma GCC diagnostic push

124

125#if defined(__clang__)

126#elif defined(__GNUC__)

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

128#endif // defined(__clang__)

129#endif // defined(__GNUC__)

130

131 // Cast required on 64-bit.

132 return static_cast<int> (ret);

133

134#if defined(__GNUC__)

135#pragma GCC diagnostic pop

136#endif // defined(__GNUC__)

137 }

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. Unconditionally noexcept, since the trace_policy concept already requires T::write() to be noexcept.

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

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

454 {

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

456 }

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

---

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.17.0.