third_party/pigweed/repo/pw_log_tokenized/docs.rst

   1 .. _module-pw_log_tokenized:
   2
   3 ----------------
   4 pw_log_tokenized
   5 ----------------
   6 ``pw_log_tokenized`` is a ``pw_log`` backend that tokenizes log messages using
   7 the ``pw_tokenizer`` module. Log messages are tokenized and passed to the
   8 ``pw_tokenizer_HandleEncodedMessageWithPayload`` function. For maximum
   9 efficiency, the log level, 16-bit tokenized module name, and flags bits are
  10 passed through the payload argument.
  11
  12 Example implementation:
  13
  14 .. code-block:: cpp
  15
  16    extern "C" void pw_tokenizer_HandleEncodedMessageWithPayload(
  17        pw_tokenizer_Payload payload, const uint8_t message[], size_t size) {
  18      // The metadata object provides the log level, module token, and flags.
  19      // These values can be recorded and used for runtime filtering.
  20      pw::log_tokenized::Metadata metadata(payload);
  21
  22      if (metadata.level() < current_log_level) {
  23        return;
  24      }
  25
  26      if (metadata.flags() & HIGH_PRIORITY_LOG != 0) {
  27        EmitHighPriorityLog(metadata.module(), message, size);
  28      } else {
  29        EmitLowPriorityLog(metadata.module(), message, size);
  30      }
  31    }
  32
  33 See the documentation for ``pw_tokenizer`` for further details.
  34
  35 Build targets
  36 -------------
  37 The GN build for ``pw_log_tokenized`` has two targets: ``pw_log_tokenized`` and
  38 ``log_backend``. The ``pw_log_tokenized`` target provides the
  39 ``pw_log_tokenized/log_tokenized.h`` header. The ``log_backend`` target
  40 implements the backend for the ``pw_log`` facade. ``pw_log_tokenized`` invokes
  41 the ``pw_tokenizer:global_handler_with_payload`` facade, which must be
  42 implemented by the user of ``pw_log_tokenized``.
  43
  44 .. note::
  45   The documentation for this module is currently incomplete.