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 raster_bytes; // bytes emitted to ttyfp
18 int64_t raster_max_bytes; // max bytes emitted for a frame
19 int64_t raster_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 uint64_t cell_geo_changes; // cell geometry changes (resizes)
46 uint64_t pixel_geo_changes;// pixel geometry changes (font resize)
47 // current state -- these can decrease
49 uint64_t fbbytes; // bytes devoted to framebuffers
50 unsigned planes; // planes currently in existence
51 } ncstats;
52 ncstats* notcurses_stats_alloc(struct notcurses* nc);
54 void notcurses_stats(struct notcurses* nc, ncstats* stats);
56 void notcurses_stats_reset(struct notcurses* nc, ncstats* stats);
58
60 notcurses_stats_alloc allocates an ncstats object. This should be used
61 rather than allocating the object in client code, to future-proof
62 against the struct being enlarged by later Notcurses versions.
63 notcurses_stats acquires an atomic snapshot of statistics, primarily
65 related to notcurses_render(3). notcurses_stats_reset does the same,
66 but also resets all cumulative stats (immediate stats such as fbbytes
67 are not reset).
68 renders is the number of successful calls to notcurses_render(3) or
70 ncpile_render_to_buffer(3). failed_renders is the number of unsuccess‐
71 ful calls to these functions. failed_renders should be 0; renders are
72 not expected to fail except under exceptional circumstances. should
73 notcurses_render(3) fail while writing out a frame to the terminal, it
74 counts as a failed render.
75 raster_max_bytes and raster_min_bytes track the maximum and minimum
77 number of bytes used rasterizing a frame. A given state of Notcurses
78 does not correspond to a unique number of bytes; the size is also de‐
79 pendent on the existing terminal state. As a first approximation, the
80 time a terminal takes to ingest and reflect a frame is dependent on the
81 size of the rasterized frame.
82 render_ns, render_max_ns, and render_min_ns track the total amount of
84 time spent rendering frames in nanoseconds. Rendering takes place in
85 ncpile_render (called by notcurses_render(3) and ncpile_render_to_buf‐
86 fer). This step is independent of the terminal.
87 raster_ns, raster_max_ns, and raster_min_ns track the total amount of
89 time spent rasterizing frames in nanoseconds. Rasterizing takes place
90 in ncpile_raster (called by notcurses_raster(3) and ncpile_ren‐
91 der_to_buffer). This step depends on the terminal definitions. The
92 same frame might not rasterize to the same bytes for different termi‐
93 nals.
94 writeout_ns, writeout_max_ns, and writeout_min_ns track the total
96 amount of time spent writing frames to the terminal. This takes place
97 in ncpile_rasterize (called by notcurses_render(3)).
98 cellemissions reflects the number of EGCs written to the terminal.
100 cellelisions reflects the number of cells which were not written, due
101 to damage detection.
102 refreshes is the number of times notcurses_refresh has been successful‐
104 ly executed.
105 fbbytes is the total number of bytes devoted to framebuffers throughout
107 the struct notcurses context. planes is the number of planes in the
108 context. Neither of these stats can reach 0, due to the mandatory
109 standard plane.
110 sprixelemissions is the number of sprixel draws. sprixelelisions is
112 the number of times a sprixel was elided--essentially, the number of
113 times a sprixel appeared in a rendered frame without freshly drawing
114 it. sprixelbytes is the number of bytes used for sprixel drawing. It
115 does not include move/delete operations, nor glyphs used to erase
116 sprixels.
117 input_errors is the number of errors while processing input, e.g. mal‐
119 formed control sequences or invalid UTF-8 (see utf8(7)).
120 hpa_gratuitous is the number of hpa (horizontal position absolute, see
122 terminfo(5)) control sequences issued where not strictly necessary.
123 This is done to cope with fundamental ambiguities regarding glyph
124 width. It is not generally possible to know how wide a glyph will be
125 rendered on a given combination of font, font rendering engine, and
126 terminal. Indeed, it is not even generally possible to know how many
127 glyphs will result from a sequence of EGCs. As a result, Notcurses
128 sometimes issues "gratuitous" hpa controls.
129 cell_geo_changes is the number of changes to the visible area's cell
131 geometry. The cell geometry changes whenever the visible area is re‐
132 sized without a corresponding cell-pixel geometry change. pix‐
133 el_geo_changes is the number of changes to cells' pixel geometry (i.e.
134 the height and width of each cell), and changes whenever the font size
135 changes. Both can change at the same time if e.g. a terminal under‐
136 goes a font size change without changing its total size.
137
139 Unsuccessful render operations do not contribute to the render timing
140 stats.
141 Linux framebuffer bitmaps are not written through the terminal device,
143 but instead directly into the memory-mapped framebuffer (see mmap(2)).
144 Bytes used for framebuffer graphics are thus independent of bytes writ‐
145 ten to the terminal. This explains why sprixelbytes may be surprising
146 given the value of raster_bytes.
147
149 Neither notcurses_stats nor notcurses_stats_reset can fail. Neither
150 returns any value. notcurses_stats_alloc returns a valid ncstats ob‐
151 ject on success, or NULL on allocation failure.
152
154 mmap(2), notcurses(3), notcurses_render(3), terminfo(5), utf8(7)
155
157 nick black <nickblack@linux.com>.
158 v3.0.8 notcurses_stats(3)