add notcurses_stats_alloc #1043

NEWS.md

@@ -9,6 +9,8 @@ rearrangements of Notcurses.
     these processes.
   * `notcurses_render_to_buffer()` has been added, allowing user control of
     the process of writing frames out to the terminal.
+  * `notcurses_stats_create()` has been added, to allocate an `ncstats` object.
+    `notcurses_reset_stats()` has been renamed `notcurses_stats_reset()`.
 
 * 1.7.5 (2020-09-29)
   * `ncreel_destroy()` now returns `void` rather than `int`.

USAGE.md

@@ -2849,11 +2849,15 @@ typedef struct ncstats {
   unsigned planes;           // number of planes currently in existence
 } ncstats;
 
+// Allocate an ncstats object. Use this rather than allocating your own, since
+// future versions of Notcurses might enlarge this structure.
+ncstats* notcurses_stats_create(const struct notcurses* nc);
+
 // Acquire an atomic snapshot of the notcurses object's stats.
 void notcurses_stats(const struct notcurses* nc, ncstats* stats);
 
 // Reset all cumulative stats (immediate ones, such as fbbytes, are not reset).
-void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);
+void notcurses_stats_reset(struct notcurses* nc, ncstats* stats);
 ```
 
 

doc/man/man3/notcurses_stats.3.md

@@ -39,14 +39,20 @@ typedef struct ncstats {
 } ncstats;
 ```
 
+**ncstats* notcurses_stats_alloc(struct notcurses* nc);**
+
 **void notcurses_stats(struct notcurses* nc, ncstats* stats);**
 
-**void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);**
+**void notcurses_stats_reset(struct notcurses* nc, ncstats* stats);**
 
 # DESCRIPTION
 
+**notcurses_stats_alloc** allocates an **ncstats** 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.
+
 **notcurses_stats** acquires an atomic snapshot of statistics, primarily
-related to notcurses_render(3). **notcurses_reset_stats** does the same, but
+related to notcurses_render(3). **notcurses_stats_reset** does the same, but
 also resets all cumulative stats (immediate stats such as **fbbytes** are not
 reset).
 
@@ -89,7 +95,9 @@ Unsuccessful render operations do not contribute to the render timing stats.
 
 # RETURN VALUES
 
-Neither of these functions can fail. Neither returns any value.
+Neither **notcurses_stats** nor **notcurses_stats_reset** can fail. Neither
+returns any value. **notcurses_stats_alloc** returns a valid **ncstats**
+object on success, or **NULL** on failure.
 
 # SEE ALSO
 

include/ncpp/NotCurses.hh

@@ -174,7 +174,7 @@ namespace ncpp
 			if (stats == nullptr)
 				throw invalid_argument ("'stats' must be a valid pointer");
 
-			notcurses_reset_stats (nc, stats);
+			notcurses_stats_reset (nc, stats);
 		}
 
 		bool use (const Palette256 *p) const

include/notcurses/notcurses.h

@@ -1119,11 +1119,15 @@ typedef struct ncstats {
   unsigned planes;           // number of planes currently in existence
 } ncstats;
 
+// Allocate an ncstats object. Use this rather than allocating your own, since
+// future versions of Notcurses might enlarge this structure.
+API ncstats* notcurses_stats_create(const struct notcurses* nc);
+
 // Acquire an atomic snapshot of the notcurses object's stats.
 API void notcurses_stats(const struct notcurses* nc, ncstats* stats);
 
 // Reset all cumulative stats (immediate ones, such as fbbytes, are not reset).
-API void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);
+API void notcurses_stats_reset(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,

python/src/notcurses/build_notcurses.py

@@ -173,8 +173,9 @@ typedef struct ncstats {
   uint64_t defaultelisions;  // default color was emitted
   uint64_t defaultemissions; // default color was elided
 } ncstats;
+ncstats* notcurses_stats_alloc(struct notcurses* nc);
 void notcurses_stats(struct notcurses* nc, ncstats* stats);
-void notcurses_reset_stats(struct notcurses* nc, ncstats* stats);
+void notcurses_stats_reset(struct notcurses* nc, ncstats* stats);
 int ncplane_hline_interp(struct ncplane* n, const cell* c, int len, uint64_t c1, uint64_t c2);
 int ncplane_vline_interp(struct ncplane* n, const cell* c, int len, uint64_t c1, uint64_t c2);
 int ncplane_box(struct ncplane* n, const cell* ul, const cell* ur, const cell* ll, const cell* lr, const cell* hline, const cell* vline, int ystop, int xstop, unsigned ctlword);

src/demo/demo.c

@@ -226,7 +226,7 @@ ext_demos(struct notcurses* nc, const char* spec, bool ignore_failures){
 
     hud_schedule(demos[idx].name);
     ret = demos[idx].fxn(nc);
-    notcurses_reset_stats(nc, &results[i].stats);
+    notcurses_stats_reset(nc, &results[i].stats);
     clock_gettime(CLOCK_MONOTONIC, &now);
     uint64_t nowns = timespec_to_ns(&now);
     results[i].timens = nowns - prevns;
@@ -582,7 +582,7 @@ int main(int argc, char** argv){
     if(notcurses_render(nc)){
       goto err;
     }
-    notcurses_reset_stats(nc, NULL);
+    notcurses_stats_reset(nc, NULL);
     if(ext_demos(nc, spec, ignore_failures)){
       goto err;
     }

src/lib/notcurses.c

@@ -715,7 +715,11 @@ void notcurses_stats(const notcurses* nc, ncstats* stats){
   memcpy(stats, &nc->stats, sizeof(*stats));
 }
 
-void notcurses_reset_stats(notcurses* nc, ncstats* stats){
+ncstats* notcurses_stats_create(const notcurses* nc __attribute__ ((unused))){
+  return malloc(sizeof(ncstats));
+}
+
+void notcurses_stats_reset(notcurses* nc, ncstats* stats){
   if(stats){
     memcpy(stats, &nc->stats, sizeof(*stats));
   }

tests/notcurses.cpp

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