.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_stats" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_stats - notcurses runtime statistics
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
typedef struct ncstats {
  // purely increasing stats
  uint64_t renders;          // number of successful renders
  uint64_t failed_renders;   // aborted renders, should be 0
  uint64_t render_bytes;     // bytes emitted to ttyfp
  int64_t render_max_bytes;  // max bytes emitted for a frame
  int64_t render_min_bytes;  // min bytes emitted for a frame
  uint64_t render_ns;        // nanoseconds spent in render+raster
  int64_t render_max_ns;     // max ns spent in render+raster for a frame
  int64_t render_min_ns;     // min ns spent in render+raster for a frame
  uint64_t writeout_ns;      // nanoseconds spent writing frames to terminal
  int64_t writeout_max_ns;   // max ns spent writing out a frame
  int64_t writeout_min_ns;   // min ns spent writing out a frame
  uint64_t cellelisions;     // cells elided entirely
  uint64_t cellemissions;    // cells emitted
  uint64_t fgelisions;       // RGB fg elision count
  uint64_t fgemissions;      // RGB fg emissions
  uint64_t bgelisions;       // RGB bg elision count
  uint64_t bgemissions;      // RGB bg emissions
  uint64_t defaultelisions;  // default color was emitted
  uint64_t defaultemissions; // default color was elided

  // current state -- these can decrease
  uint64_t fbbytes;          // bytes devoted to framebuffers
  unsigned planes;           // planes currently in existence
} ncstats;
\f[R]
.fi
.PP
\f[B]ncstats* notcurses_stats_alloc(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B]);\f[R]
.PP
\f[B]void notcurses_stats(struct notcurses* \f[R]\f[I]nc\f[R]\f[B],
ncstats* \f[R]\f[I]stats\f[R]\f[B]);\f[R]
.PP
\f[B]void notcurses_stats_reset(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], ncstats* \f[R]\f[I]stats\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
\f[B]notcurses_stats_alloc\f[R] allocates an \f[B]ncstats\f[R] object.
This should be used rather than allocating the object in client code, to
future-proof against the struct being enlarged by later Notcurses
versions.
.PP
\f[B]notcurses_stats\f[R] acquires an atomic snapshot of statistics,
primarily related to notcurses_render(3).
\f[B]notcurses_stats_reset\f[R] does the same, but also resets all
cumulative stats (immediate stats such as \f[B]fbbytes\f[R] are not
reset).
.PP
\f[B]renders\f[R] is the number of successful calls to
\f[B]notcurses_render(3)\f[R] or
\f[B]notcurses_render_to_buffer(3)\f[R].
\f[B]failed_renders\f[R] is the number of unsuccessful calls to these
functions.
\f[B]failed_renders\f[R] should be 0; renders are not expected to fail
except under exceptional circumstances.
should \f[B]notcurses_render(3)\f[R] fail while writing out a frame to
the terminal, it counts as a failed render.
.PP
\f[B]render_max_bytes\f[R] and \f[B]render_min_bytes\f[R] track the
maximum and minimum number of bytes used rasterizing a frame.
A given state of Notcurses does not correspond to a unique number of
bytes; the size is also dependent on the existing terminal state.
As a first approximation, the time a terminal takes to ingest and
reflect a frame is dependent on the size of the rasterized frame.
.PP
\f[B]render_ns\f[R], \f[B]render_max_ns\f[R], and
\f[B]render_min_ns\f[R] track the total amount of time spent rendering
and rasterizing frames in nanoseconds.
Rendering and rasterizing takes place in \f[B]notcurses_render(3)\f[R],
and is the entirety of \f[B]notcurses_render_to_buffer(3)\f[R].
These steps are independent of the terminal.
.PP
\f[B]writeout_ns\f[R], \f[B]writeout_max_ns\f[R], and
\f[B]writeout_min_ns\f[R] track the total amount of time spent writing
frames to the terminal.
This takes place in only \f[B]notcurses_render(3)\f[R].
If \f[B]notcurses_render_to_buffer(3)\f[R] is used, the user is
responsible for writing out the frame, and it will not be tracked by any
stat.
.PP
\f[B]cellemissions\f[R] reflects the number of EGCs written to the
terminal.
\f[B]cellelisions\f[R] reflects the number of cells which were not
written, due to damage detection.
.PP
\f[B]fbbytes\f[R] is the total number of bytes devoted to framebuffers
throughout the \f[B]struct notcurses\f[R] context.
\f[B]planes\f[R] is the number of planes in the context.
Neither of these stats can reach 0, due to the mandatory standard plane.
.SH NOTES
.PP
Unsuccessful render operations do not contribute to the render timing
stats.
.SH RETURN VALUES
.PP
Neither \f[B]notcurses_stats\f[R] nor \f[B]notcurses_stats_reset\f[R]
can fail.
Neither returns any value.
\f[B]notcurses_stats_alloc\f[R] returns a valid \f[B]ncstats\f[R] object
on success, or \f[B]NULL\f[R] on failure.
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_render(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.