diff --git a/NEWS.md b/NEWS.md index 99f5fc3ac..e8dd7712b 100644 --- a/NEWS.md +++ b/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`. diff --git a/USAGE.md b/USAGE.md index 2941e2e26..0a7ce08e8 100644 --- a/USAGE.md +++ b/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); ``` diff --git a/doc/man/man3/notcurses_stats.3.md b/doc/man/man3/notcurses_stats.3.md index c53018900..dfbe65b1e 100644 --- a/doc/man/man3/notcurses_stats.3.md +++ b/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 diff --git a/include/ncpp/NotCurses.hh b/include/ncpp/NotCurses.hh index c6c5b7e41..a4daef1a4 100644 --- a/include/ncpp/NotCurses.hh +++ b/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 diff --git a/include/notcurses/notcurses.h b/include/notcurses/notcurses.h index 3fbdca7c7..390b4eea3 100644 --- a/include/notcurses/notcurses.h +++ b/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, diff --git a/python/src/notcurses/build_notcurses.py b/python/src/notcurses/build_notcurses.py index 60bf35543..2564054ea 100644 --- a/python/src/notcurses/build_notcurses.py +++ b/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); diff --git a/src/demo/demo.c b/src/demo/demo.c index cea18f83f..676e29da8 100644 --- a/src/demo/demo.c +++ b/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; } diff --git a/src/lib/notcurses.c b/src/lib/notcurses.c index e99bc4648..2858291d8 100644 --- a/src/lib/notcurses.c +++ b/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)); } diff --git a/tests/notcurses.cpp b/tests/notcurses.cpp index 03e9505a6..20858613b 100644 --- a/tests/notcurses.cpp +++ b/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); }