1notcurses_stats(3) notcurses_stats(3)
2
6 notcurses_stats - notcurses runtime statistics
7
9 #include <notcurses/notcurses.h>
10 typedef struct ncstats {
12 // purely increasing stats
13 uint64_t renders; // successful ncpile_render() runs
14 uint64_t writeouts; // successful ncpile_rasterize() runs
15 uint64_t failed_renders; // aborted renders, should be 0
16 uint64_t failed_writeouts; // aborted writes
17 uint64_t render_bytes; // bytes emitted to ttyfp
18 int64_t render_max_bytes; // max bytes emitted for a frame
19 int64_t render_min_bytes; // min bytes emitted for a frame
20 uint64_t render_ns; // nanoseconds spent rendering
21 int64_t render_max_ns; // max ns spent for a frame
22 int64_t render_min_ns; // min ns spent for a frame
23 uint64_t raster_ns; // nanoseconds spent rasterizing
24 int64_t raster_max_ns; // max ns spent in raster for a frame
25 int64_t raster_min_ns; // min ns spent in raster for a frame
26 uint64_t writeout_ns; // ns spent writing frames to terminal
27 int64_t writeout_max_ns; // max ns spent writing out a frame
28 int64_t writeout_min_ns; // min ns spent writing out a frame
29 uint64_t cellelisions; // cells elided entirely
30 uint64_t cellemissions; // cells emitted
31 uint64_t fgelisions; // RGB fg elision count
32 uint64_t fgemissions; // RGB fg emissions
33 uint64_t bgelisions; // RGB bg elision count
34 uint64_t bgemissions; // RGB bg emissions
35 uint64_t defaultelisions; // default color was emitted
36 uint64_t defaultemissions; // default color was elided
37 uint64_t refreshes; // refreshes (unoptimized redraws)
38 uint64_t sprixelemissions; // sprixel draw count
39 uint64_t sprixelelisions; // sprixel elision count
40 uint64_t sprixelbytes; // sprixel bytes emitted
41 uint64_t appsync_updates; // application-synchronized updates
42 uint64_t input_events; // inputs received or synthesized
43 uint64_t input_errors; // errors processing input
44 uint64_t hpa_gratuitous; // gratuitous HPAs issued
45 // current state -- these can decrease
47 uint64_t fbbytes; // bytes devoted to framebuffers
48 unsigned planes; // planes currently in existence
49 } ncstats;
50 ncstats* notcurses_stats_alloc(struct notcurses* nc);
52 void notcurses_stats(struct notcurses* nc, ncstats* stats);
54 void notcurses_stats_reset(struct notcurses* nc, ncstats* stats);
56
58 notcurses_stats_alloc allocates an ncstats object. This should be used
59 rather than allocating the object in client code, to future-proof
60 against the struct being enlarged by later Notcurses versions.
61 notcurses_stats acquires an atomic snapshot of statistics, primarily
63 related to notcurses_render(3). notcurses_stats_reset does the same,
64 but also resets all cumulative stats (immediate stats such as fbbytes
65 are not reset).
66 renders is the number of successful calls to notcurses_render(3) or
68 ncpile_render_to_buffer(3). failed_renders is the number of unsuccess‐
69 ful calls to these functions. failed_renders should be 0; renders are
70 not expected to fail except under exceptional circumstances. should
71 notcurses_render(3) fail while writing out a frame to the terminal, it
72 counts as a failed render.
73 render_max_bytes and render_min_bytes track the maximum and minimum
75 number of bytes used rasterizing a frame. A given state of Notcurses
76 does not correspond to a unique number of bytes; the size is also de‐
77 pendent on the existing terminal state. As a first approximation, the
78 time a terminal takes to ingest and reflect a frame is dependent on the
79 size of the rasterized frame.
80 render_ns, render_max_ns, and render_min_ns track the total amount of
82 time spent rendering frames in nanoseconds. Rendering takes place in
83 ncpile_render (called by notcurses_render(3) and ncpile_render_to_buf‐
84 fer). This step is independent of the terminal.
85 raster_ns, raster_max_ns, and raster_min_ns track the total amount of
87 time spent rasterizing frames in nanoseconds. Rasterizing takes place
88 in ncpile_raster (called by notcurses_raster(3) and ncpile_ren‐
89 der_to_buffer). This step depends on the terminal definitions. The
90 same frame might not rasterize to the same bytes for different termi‐
91 nals.
92 writeout_ns, writeout_max_ns, and writeout_min_ns track the total
94 amount of time spent writing frames to the terminal. This takes place
95 in ncpile_rasterize (called by notcurses_render(3)).
96 cellemissions reflects the number of EGCs written to the terminal.
98 cellelisions reflects the number of cells which were not written, due
99 to damage detection.
100 refreshes is the number of times notcurses_refresh has been successful‐
102 ly executed.
103 fbbytes is the total number of bytes devoted to framebuffers throughout
105 the struct notcurses context. planes is the number of planes in the
106 context. Neither of these stats can reach 0, due to the mandatory
107 standard plane.
108 sprixelemissions is the number of sprixel draws. sprixelelisions is
110 the number of times a sprixel was elided--essentially, the number of
111 times a sprixel appeared in a rendered frame without freshly drawing
112 it. sprixelbytes is the number of bytes used for sprixel drawing. It
113 does not include move/delete operations, nor glyphs used to erase
114 sprixels.
115 input_errors is the number of errors while processing input, e.g. mal‐
117 formed control sequences or invalid UTF-8 (see utf8(7)).
118 hpa_gratuitous is the number of hpa (horizontal position absolute, see
120 terminfo(5)) control sequences issued where not strictly necessary.
121 This is done to cope with fundamental ambiguities regarding glyph
122 width. It is not generally possible to know how wide a glyph will be
123 rendered on a given combination of font, font rendering engine, and
124 terminal. Indeed, it is not even generally possible to know how many
125 glyphs will result from a sequence of EGCs. As a result, Notcurses
126 sometimes issues "gratuitous" hpa controls.
127
129 Unsuccessful render operations do not contribute to the render timing
130 stats.
131 Linux framebuffer bitmaps are not written through the terminal device,
133 but instead directly into the memory-mapped framebuffer (see mmap(2)).
134 Bytes used for framebuffer graphics are thus independent of bytes writ‐
135 ten to the terminal. This explains why sprixelbytes may be surprising
136 given the value of render_bytes.
137
139 Neither notcurses_stats nor notcurses_stats_reset can fail. Neither
140 returns any value. notcurses_stats_alloc returns a valid ncstats ob‐
141 ject on success, or NULL on failure.
142
144 mmap(2), notcurses(3), notcurses_render(3), terminfo(5), utf8(7)
145
147 nick black <nickblack@linux.com>.
148 v2.4.9 notcurses_stats(3)