notcurses_stats man page #213

CMakeLists.txt

@@ -139,9 +139,9 @@ foreach(m ${MANSOURCE3})
     ARGS -5 --pipe ${m} > ${CMAKE_CURRENT_BINARY_DIR}/${me}.html
     COMMENT "Building HTML5 ${me}.html"
   )
-  add_custom_target(${me}.html
+  add_custom_target(${me}.html5
     ALL
-    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${me}
+    DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${me}.html
   )
   endforeach()
 endif()

README.md

@@ -2133,11 +2133,11 @@ typedef struct ncstats {
   uint64_t defaultemissions; // default color was elided
 } ncstats;
 
-// Acquire a snapshot of the notcurses object's stats.
-void notcurses_stats(const struct notcurses* nc, ncstats* stats);
+// Acquire an atomic snapshot of the notcurses object's stats.
+void notcurses_stats(struct notcurses* nc, ncstats* stats);
 
-// Reset all stats.
-void notcurses_reset_stats(struct notcurses* nc);
+// Reset all cumulative stats (immediate ones, such as fbbytes, are not reset).
+void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);
 ```
 
 Timings for renderings are across the breadth of `notcurses_render()`: they

doc/man/man3/index.txt

@@ -7,6 +7,7 @@ notcurses_cell(3)     notcurses_cell.3.ronn
 notcurses_input(3)    notcurses_input.3.ronn
 notcurses_output(3)   notcurses_output.3.ronn
 notcurses_render(3)   notcurses_render.3.ronn
+notcurses_stats(3)    notcurses_stats.3.ronn
 notcurses_stop(3)     notcurses_stop.3.ronn
 
 poll(2)               http://man7.org/linux/man-pages/man2/poll.2.html
@@ -16,3 +17,4 @@ ncurses(3NCURSES)     http://man7.org/linux/man-pages/man3/ncurses.3x.html
 terminfo(5)           http://man7.org/linux/man-pages/man5/terminfo.5.html
 signal(7)             http://man7.org/linux/man-pages/man7/signal.7.html
 unicode(7)            http://man7.org/linux/man-pages/man7/unicode.7.html
+utf-8(7)              http://man7.org/linux/man-pages/man7/utf-8.7.html

doc/man/man3/notcurses.3.ronn

@@ -67,7 +67,7 @@ signals which would normally terminate the process. The new handlers will try
 to call notcurses_stop(3), and then propagate the received signal to the
 previous action.
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_cell.3.ronn

@@ -10,7 +10,7 @@ notcurses_cell(3) -- operations on notcurses cells
 
 ## RETURN VALUES
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_init.3.ronn

@@ -109,7 +109,7 @@ geometry.
 `NULL` is returned on failure. Otherwise, the return value points at a valid
 `struct notcurses`, which can be used until it is provided to notcurses_stop(3).
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_input.3.ronn

@@ -31,7 +31,7 @@ notcurses_input(3) -- input via notcurses
 
 ## RETURN VALUES
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_ncplane.3.ronn

@@ -48,7 +48,7 @@ notcurses_ncplane(3) -- operations on notcurses planes
 
 ## RETURN VALUES
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_ncvisual.3.ronn

@@ -10,7 +10,7 @@ notcurses_ncvisual(3) -- notcurses multimedia
 
 ## RETURN VALUES
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_newplane.3.ronn

@@ -12,7 +12,7 @@ notcurses_newplane(3) -- create a new ncplane atop the z-buffer
 
 ## RETURN VALUES
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_output.3.ronn

@@ -10,7 +10,7 @@ notcurses_output(3) -- output to ncplanes
 
 ## RETURN VALUES
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_render.3.ronn

@@ -35,7 +35,7 @@ dependencies between cells.
 Recall that there is a total ordering on the N ncplanes, and that the standard
 plane always exists, with geometry equal to the physical screen. Each cell of
 the physical screen is thus intersected by some totally ordered subset of
-planes `P0`, `P1`…`Pi`, where 0 < `i` ≤ `N`. At each cell, rendering starts at
+planes `P0`, `P1`...`Pi`, where 0 < `i` ≤ `N`. At each cell, rendering starts at
 the topmost intersecting plane `P0`. The algorithm descends until either:
 
 * it has locked in an extended grapheme cluster, and fore/background colors, or
@@ -65,11 +65,11 @@ and "default background color" inherited from the terminal. Since
 notcurses doesn't know what these colors are, they are not considered for
 purposes of color blending.
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 
 ## SEE ALSO
 
-notcurses_cell(3), notcurses_ncplane(3), notcurses_output(3), console_codes(4),
-utf-8(7)
+notcurses_cell(3), notcurses_ncplane(3), notcurses_output(3),
+notcurses_stats(3), console_codes(4), utf-8(7)

doc/man/man3/notcurses_stats.3.ronn

@@ -0,0 +1,49 @@
+notcurses_stats(3) -- notcurses runtime statistics
+==================================================
+
+## SYNOPSIS
+
+`#include <notcurses.h>`
+
+<pre>typedef struct ncstats {
+  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 rendering
+  int64_t render_max_ns;     // max ns spent rendering
+  int64_t render_min_ns;     // min ns spent rendering
+  uint64_t cellelisions;     // cells elided entirely
+  uint64_t cellemissions;    // cells emitted
+  uint64_t fbbytes;          // bytes devoted to framebuffers
+  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
+} ncstats;</pre>
+
+`void notcurses_stats(struct notcurses* nc, ncstats* stats);`
+
+`void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);`
+
+## DESCRIPTION
+
+`notcurses_stats` acquires an atomic snapshot of statistics, primarily
+related to notcurses_render(3). `notcurses_reset_stats` does the same, but
+also resets all cumulative stats (immediate stats such as `fbbytes` are not
+reset).
+
+## RETURN VALUES
+
+Neither of these functions can fail. Neither returns any value.
+
+## AUTHOR
+
+Nick Black <nickblack@linux.com>
+
+## SEE ALSO
+
+notcurses_render(3)

doc/man/man3/notcurses_stdplane.3.ronn

@@ -27,7 +27,7 @@ A resize event does not invalidate this reference; it can be used until
 These functions cannot fail when provided a valid `struct notcurses*`. They
 will always return a valid pointer to the standard plane.
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

doc/man/man3/notcurses_stop.3.ronn

@@ -18,7 +18,7 @@ place by notcurses_init(3). `nc` must not be used following the call.
 
 On success, 0 is returned. Otherwise, a negative value is returned.
 
-## AUTHORS
+## AUTHOR
 
 Nick Black <nickblack@linux.com>
 

include/notcurses.h

@@ -359,11 +359,11 @@ typedef struct ncstats {
   uint64_t defaultemissions; // default color was elided
 } ncstats;
 
-// Acquire a snapshot of the notcurses object's stats.
-API void notcurses_stats(const struct notcurses* nc, ncstats* stats);
+// Acquire an atomic snapshot of the notcurses object's stats.
+API void notcurses_stats(struct notcurses* nc, ncstats* stats);
 
-// Reset all stats.
-API void notcurses_reset_stats(struct notcurses* nc);
+// Reset all cumulative stats (immediate ones, such as fbbytes, are not reset).
+API void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);
 
 // Resize the specified ncplane. The four parameters 'keepy', 'keepx',
 // 'keepleny', and 'keeplenx' define a subset of the ncplane to keep,
@@ -835,7 +835,7 @@ channel_default_p(unsigned channel){
 // Mark the channel as using its default color, which also marks it opaque.
 static inline unsigned
 channel_set_default(unsigned* channel){
-  return *channel &= (~CELL_BGDEFAULT_MASK | ~CELL_ALPHA_HIGHCONTRAST);
+  return *channel &= ~(CELL_BGDEFAULT_MASK | CELL_ALPHA_HIGHCONTRAST);
 }
 
 // Extract the 32-bit background channel from a channel pair.
@@ -1003,6 +1003,9 @@ channels_set_bg_default(uint64_t* channels){
 // Returns the result of blending two channels.
 static inline unsigned
 channels_blend(unsigned c1, unsigned c2){
+  if(channel_default_p(c1)){
+    return c1;
+  }
   int rsum = (channel_get_r(c1) + channel_get_r(c2)) / 2;
   int gsum = (channel_get_g(c1) + channel_get_g(c2)) / 2;
   int bsum = (channel_get_b(c1) + channel_get_b(c2)) / 2;

src/demo/demo.c

@@ -264,8 +264,7 @@ ext_demos(struct notcurses* nc, const char* demos){
         ret = -1;
         break;
     }
-    notcurses_stats(nc, &results[i].stats);
-    notcurses_reset_stats(nc);
+    notcurses_reset_stats(nc, &results[i].stats);
     clock_gettime(CLOCK_MONOTONIC, &now);
     uint64_t nowns = timespec_to_ns(&now);
     results[i].timens = nowns - prevns;

src/lib/notcurses.c

@@ -159,10 +159,6 @@ const char* notcurses_version(void){
   return NOTCURSES_VERSION;
 }
 
-void notcurses_stats(const notcurses* nc, ncstats* stats){
-  memcpy(stats, &nc->stats, sizeof(*stats));
-}
-
 void* ncplane_set_userptr(ncplane* n, void* opaque){
   void* ret = n->userptr;
   n->userptr = opaque;
@@ -660,8 +656,15 @@ stash_stats(notcurses* nc){
   reset_stats(&nc->stats);
 }
 
-void notcurses_reset_stats(notcurses* nc){
+void notcurses_stats(notcurses* nc, ncstats* stats){
   pthread_mutex_lock(&nc->lock);
+  memcpy(stats, &nc->stats, sizeof(*stats));
+  pthread_mutex_unlock(&nc->lock);
+}
+
+void notcurses_reset_stats(notcurses* nc, ncstats* stats){
+  pthread_mutex_lock(&nc->lock);
+  memcpy(stats, &nc->stats, sizeof(*stats));
   stash_stats(nc);
   pthread_mutex_unlock(&nc->lock);
 }

tests/notcurses.cpp

@@ -130,7 +130,7 @@ TEST_CASE("NotcursesBase") {
     CHECK(0 == notcurses_render(nc_));
     notcurses_stats(nc_, &stats);
     CHECK(1 == stats.renders);
-    notcurses_reset_stats(nc_);
+    notcurses_reset_stats(nc_, &stats);
     notcurses_stats(nc_, &stats);
     CHECK(0 == stats.renders);
   }