Object monitor

Browse source code on GitHub

Overview

This sample runs a small application and, next to it, a monitor thread that uses object cores to draw a live table of the kernel objects in the system. Where the Object cores sample walks through the facility step by step, this one shows it the way a debugging tool would use it: continuously, on objects it did not create itself.

The application is a job server:

  • a sensor thread posts samples into a message queue;

  • a dispatcher starts short-lived job threads, up to four at a time, each with a heap-allocated request that embeds a semaphore, a mutex and a timer;

  • every job waits on a stack-local semaphore for each of its processing steps, then frees its request and exits.

Threads, requests and their embedded objects therefore appear and disappear all the time. The monitor refreshes every second and prints:

  • the number of objects of each type, with the skipped count of objects that were not registered because they live in stack storage (the job step semaphores) and the dropped count of registrations refused because the registry was full;

  • every thread with its state and its share of the CPU over the last period, computed from the runtime statistics that k_obj_core_stats_query() returns for threads and for the kernel;

  • the number of jobs started, finished and running.

Lowering CONFIG_OBJ_CORE_MAX_DYNAMIC_OBJECTS below the peak number of run-time objects (about 24 here) makes the dropped column count up as the registry overflows, without any effect on the application. From then on the table is no longer complete: objects exist that no walk reports.

Building and Running

This application can be built and executed on QEMU as follows:

west build -b qemu_x86 samples/kernel/object_monitor
west build -t run

To build for another board, change qemu_x86 above to that board’s name. On native_sim threads run on host stacks, so the sample enables CONFIG_ARCH_POSIX_UPDATE_STACK_INFO to let the kernel recognize objects in stack storage.

By default the monitor clears the terminal and redraws in place. Set CONFIG_SAMPLE_MONITOR_CLEAR_SCREEN to n to let the output scroll, and CONFIG_SAMPLE_MONITOR_PERIOD_MS to change the refresh period.

The sample.kernel.object_monitor.tracking configuration in tests.yaml builds the same program with CONFIG_TRACING_OBJECT_TRACKING, which enables the object core framework through the tracing subsystem.

Sample Output

Object monitor   uptime 92.3s   refresh 181

  type           objects  skipped  dropped
  thread               6        0        0
  semaphore            2      801        0
  mutex                2        0        0
  timer                2        0        0
  message queue        1        0        0

  thread       address    state        cpu
  monitor      0x1105a0  running     0.5%
  idle         0x110500  ready      96.7%
  dispatcher   0x110160  sleeping    0.0%
  sensor       0x1100c0  sleeping    0.0%
  job-132      0x1103e0  pending     2.3%
  job-133      0x110340  pending     0.2%

  jobs: 133 started, 131 finished, 2 running; samples dropped: 23

Two jobs are running, so two requests exist and the semaphore, mutex and timer counts are each two objects above the static ones (the message queue is the only static object besides the threads). The 801 skipped semaphores are the step semaphores of all the jobs so far; none of them was ever registered.

See also

Object Core APIs
Object Core Statistics APIs