marsrs-react-native-xlog 0.1.0-alpha.3 → 0.1.0-alpha.4

package/ios/include/mars_xlog.h

@@ -27,9 +27,13 @@
  * caller can include it without running cbindgen. It is kept in sync with
  * `src/abi.rs` by `tests/header_sync.rs`.
  *
- * Threading: every symbol may be called from any thread. `mars_xlog_open`,
- * `mars_xlog_close` and the setters mutate process-wide state (exactly like the
- * C++ globals) and should be called from one place during start-up / shut-down.
+ * Threading: every symbol may be called from any thread. The setters and the
+ * instance lifecycle mutate shared state (exactly like the C++ globals) and
+ * should be called from one place during start-up / shut-down. What no symbol
+ * here does is install a process-wide appender: an app opens an instance with
+ * `mars_xlog_new_instance` and writes through the handle it answers. Handle
+ * `0` names no appender at all — it is what an open that failed answers, and
+ * every symbol asked of it is a no-op.
  *
  * Panics: no Rust panic ever crosses this boundary. Every entry point is
  * wrapped in `catch_unwind`; a panic is reported as `MARS_XLOG_ERR_PANIC` (or
@@ -39,6 +43,17 @@
 #ifndef MARS_XLOG_H_
 #define MARS_XLOG_H_
 
+/* The symbols this header declares are the ones `#[no_mangle]` exports: plain
+ * C names, and a C++ translation unit that includes this and calls
+ * `mars_xlog_new_instance()` asks its linker for a mangled one that does not
+ * exist.
+ * `mars_stn.h` and `mars_sdt.h` carry the same guard, and `mars_xlog.hpp` —
+ * the C++ face of this seam — includes this one, so a C++ caller asks for the
+ * same names whichever of the two it takes. */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /* --- enums ------------------------------------------------------------- */
 
 /** Mirrors `mars::xlog::TAppenderMode` (appender.h). */
@@ -60,8 +75,14 @@ typedef enum {
 /** Additional level understood only by the filter: disables every record. */
 #define MARS_LEVEL_NONE 6
 
-/* --- return codes ------------------------------------------------------- */
-
+/* --- return codes -------------------------------------------------------
+ *
+ * The five from `NULL_CONFIG` to `APPENDER` are the reasons an open may be
+ * refused, and no symbol hands them out: `mars_xlog_new_instance` answers the
+ * handle `0` for every one of them, there being no room in a handle for a
+ * negative code. They are here for the caller that wants to name the reason in
+ * its own diagnostic, not to switch on an answer.
+ */
 #define MARS_XLOG_OK 0
 #define MARS_XLOG_ERR_NULL_CONFIG (-1)   /* `config` was NULL                     */
 #define MARS_XLOG_ERR_BAD_MODE (-2)      /* `mode` outside MarsAppenderMode       */
@@ -73,17 +94,6 @@ typedef enum {
 #define MARS_XLOG_ERR_NO_PATH (-8)       /* no current log file is open           */
 #define MARS_XLOG_ERR_PANIC (-99)        /* a Rust panic was caught at the boundary */
 
-/* --- `mars_xlog_oneshot_flush` result: mars::xlog::TFileIOAction --------- */
-
-#define MARS_XLOG_ACTION_NONE 0
-#define MARS_XLOG_ACTION_SUCCESS 1
-#define MARS_XLOG_ACTION_UNNECESSARY 2  /* there was nothing to flush        */
-#define MARS_XLOG_ACTION_OPEN_FAILED 3
-#define MARS_XLOG_ACTION_READ_FAILED 4
-#define MARS_XLOG_ACTION_WRITE_FAILED 5
-#define MARS_XLOG_ACTION_CLOSE_FAILED 6
-#define MARS_XLOG_ACTION_REMOVE_FAILED 7
-
 /* --- config ------------------------------------------------------------- */
 
 /**
@@ -95,7 +105,7 @@ typedef enum {
 typedef struct {
     int mode;              /* MarsAppenderMode; default when unset: Async   */
     const char* log_dir;   /* mandatory, directory is created if missing     */
-    const char* name_prefix; /* used verbatim; no default, as in C++      */
+    const char* name_prefix; /* used verbatim; no default; "" is refused  */
     const char* pub_key;   /* NULL / "" => logs are written unencrypted      */
     int compress_mode;     /* MarsCompressMode; default when unset: Zlib     */
     int compress_level;    /* <= 0 => keep the appender default (6)          */
@@ -103,79 +113,44 @@ typedef struct {
     int cache_days;        /* < 0 => 0; 0 => keep every file                 */
 } MarsXLogConfig;
 
-/* --- lifecycle ---------------------------------------------------------- */
-
-/**
- * Replaces `mars::xlog::appender_open(const XLogConfig&)`.
- *
- * @return MARS_XLOG_OK (0) on success, or a negative MARS_XLOG_ERR_* code.
- */
-int mars_xlog_open(const MarsXLogConfig* config);
-
-/**
- * Replaces `mars::xlog::XloggerWrite(...)` / `appender_write`. The record is
- * dropped (cheaply, before any formatting) when `level` is below the level set
- * by `mars_xlog_set_level`.
- *
- * `tag`, `filename`, `func_name` and `message` may be NULL; NULL and invalid
- * UTF-8 are treated as an empty string.
- */
-void mars_xlog_write(int level,
-                     const char* tag,
-                     const char* filename,
-                     const char* func_name,
-                     int line,
-                     const char* message);
-
-/** Replaces `mars::xlog::appender_flush()` — signals the writer thread. */
-void mars_xlog_flush(void);
-
-/** Replaces `mars::xlog::appender_flush_sync()` — flushes and waits. */
-void mars_xlog_flush_sync(void);
-
-/** Replaces `mars::xlog::appender_close()`. */
-void mars_xlog_close(void);
-
-/** Replaces `xlogger_SetLevel()`; `level` < 0 clamps to Verbose. */
-void mars_xlog_set_level(int level);
-
-/** Replaces `appender_set_console_log(bool)`; `open` != 0 means on. */
-void mars_xlog_set_console_log(int open);
-
-/** Replaces `appender_set_max_file_size(uint64_t)`; 0 means "do not split". */
-void mars_xlog_set_max_file_size(unsigned long long bytes);
-
-/** Replaces `appender_set_max_alive_duration(long)`; negative clamps to 0. */
-void mars_xlog_set_max_alive_duration(long long seconds);
-
-/**
- * Replaces `appender_get_current_log_path(char*, unsigned int)`.
- *
- * Writes the NUL-terminated path of the log file currently being appended to
- * into `out` (which must hold at least `len` bytes).
- *
- * @return the number of bytes written excluding the terminating NUL, or a
- *         negative MARS_XLOG_ERR_* code (`MARS_XLOG_ERR_NULL_OUT`,
- *         `MARS_XLOG_ERR_NO_SPACE`, `MARS_XLOG_ERR_NO_PATH`).
- */
-int mars_xlog_current_log_path(char* out, unsigned int len);
-
 /* ---- logger instances (mars::xlog::NewXloggerInstance and friends) ----
  *
  * Each instance owns an appender: its own log directory, prefix, key, mode and
- * cache file. Handle 0 means "the process-wide appender opened by
- * mars_xlog_open".
+ * cache file. A C caller that wants a logger opens one with
+ * mars_xlog_new_instance and holds the handle it answers.
+ *
+ * Every call that can be asked of an instance exists only in this spelling:
+ * the C++ has a free function for its process-wide appender and a
+ * handle-taking one beside it, and a second spelling of the same operation
+ * here would be two ways to say one thing. There is no process-wide appender
+ * to install, so there is no free-function spelling either — and handle `0`,
+ * which is what a failed open answers, names no appender: the level, the mode,
+ * the console, the two sizes and the drain asked of it do nothing, and the
+ * questions answer "no" or `MARS_XLOG_ERR_NO_PATH`.
  */
 
+/* --- writing ------------------------------------------------------------- */
+
 /* Returns the instance handle, or 0 on a null/invalid config. */
 long long mars_xlog_new_instance(const MarsXLogConfig* config, int level);
 
 /* The handle registered for name_prefix, or 0 when there is none. */
 long long mars_xlog_get_instance(const char* name_prefix);
 
-/* Releases the instance and closes its appender. */
+/* Releases the instance and closes its appender. Prefer the handle-aware
+ * mars_xlog_release_instance_of() when the caller holds an instance handle. */
 void mars_xlog_release_instance(const char* name_prefix);
 
+/* The same, and only while name_prefix is still registered under `instance`.
+ *
+ * Releasing takes the prefix and not the handle, so asking
+ * mars_xlog_get_instance and then calling mars_xlog_release_instance is two
+ * answers and not one: an open of the same prefix that lands between the two is
+ * handed a handle of its own, and the release closes that one. This is the
+ * question and the release in one call, which is also what makes a second
+ * close of a prefix a no-op however many callers hold its handle. */
+void mars_xlog_release_instance_of(const char* name_prefix, long long instance);
+
 /* Writes through an instance; honours the instance's level. */
 void mars_xlog_write_instance(long long instance,
                               int level,
@@ -191,22 +166,31 @@ int mars_xlog_is_enabled_for(long long instance, int level);
 /* The instance's level, or -1 for an unknown handle. */
 int mars_xlog_get_level(long long instance);
 
-/* SetLevel for an instance (0 = the default logger). */
+/* SetLevel for an instance: the level `mars_xlog_get_level` and
+ * `mars_xlog_is_enabled_for` answer, and the one a write through the same
+ * handle asks. A no-op for handle `0`, which is no instance at all. */
 void mars_xlog_set_level_instance(long long instance, int level);
 
-/* appender_setmode: switches the process-wide appender between async/sync. */
-void mars_xlog_set_mode(int mode);
-
-/* SetAppenderMode for an instance. */
+/* appender_setmode / SetAppenderMode for an instance. */
 void mars_xlog_set_mode_instance(long long instance, int mode);
 
-/* Drains an instance; sync != 0 waits for the write to complete. */
-void mars_xlog_flush_instance(long long instance, int sync);
-
-/* FlushAll: drains the process-wide appender *and* every instance. */
-void mars_xlog_flush_all(int sync);
-
-/* SetConsoleLogOpen for an instance (0 = the default logger). */
+/* Drains an instance, requested: the writer thread is told it may drain, and
+ * this returns at once. Nothing is in the file because this returned, and
+ * nothing answers when the drain is over. The C++'s name for this call is
+ * `appender_flush`, and "flush" there said which mode the appender was opened
+ * in and not what the call does to the thread it was called on: the port names
+ * the drain by what the caller gets back, and what this one gives is no answer
+ * at all — hence "request", which is the one thing the two drains that do
+ * answer, `mars_xlog_flush_now_instance` and the awaited `flush()` every
+ * platform carries, do give. */
+void mars_xlog_request_flush_instance(long long instance);
+
+/* Drains an instance on the calling thread, which is what
+ * `appender_flush_sync` is: its records are on the disk when this returns, and
+ * that is a promise the requested call above does not make. */
+void mars_xlog_flush_now_instance(long long instance);
+
+/* SetConsoleLogOpen for an instance. */
 void mars_xlog_set_console_log_instance(long long instance, int open);
 
 /* SetMaxFileSize for an instance; 0 means "do not split". */
@@ -215,51 +199,44 @@ void mars_xlog_set_max_file_size_instance(long long instance, unsigned long long
 /* SetMaxAliveTime for an instance; negative clamps to 0. */
 void mars_xlog_set_max_alive_duration_instance(long long instance, long long seconds);
 
-/**
- * Replaces `mars::xlog::appender_oneshot_flush()`: drains the
- * `<prefix>[_<n>].mmap3` cache files another process left behind, without
- * opening an appender. The ones a live writer of this process — or of any
- * other — still holds are left alone, so it answers
- * MARS_XLOG_ACTION_UNNECESSARY when there is nothing of a dead process's to
- * recover.
- *
- * @return one of the MARS_XLOG_ACTION_* values (0..7), or a negative
- *         MARS_XLOG_ERR_* code when `config` is unusable.
- */
-int mars_xlog_oneshot_flush(const MarsXLogConfig* config);
-
 /**
  * Replaces `mars::xlog::appender_make_logfile_name()`: the log file *name* for
  * the day `timespan` days ago (0 = today), whether or not it exists yet.
  *
  * The C++ fills a `std::vector`; a C caller walks the same list with `index`,
- * starting at 0 and stopping at MARS_XLOG_ERR_NO_PATH. `prefix` and `log_dir`
- * may be NULL (an empty `log_dir` yields no name at all).
+ * starting at 0 and stopping at MARS_XLOG_ERR_NO_PATH. `instance` is a handle
+ * from `mars_xlog_new_instance`; a handle no appender is open for answers
+ * MARS_XLOG_ERR_NO_PATH from the first index.
  *
  * @return the number of bytes written excluding the terminating NUL, or a
  *         negative MARS_XLOG_ERR_* code.
  */
-int mars_xlog_make_logfile_name(int timespan,
-                                const char* prefix,
-                                const char* log_dir,
-                                unsigned int index,
-                                char* out,
-                                unsigned int len);
+int mars_xlog_make_logfile_name_instance(long long instance,
+                                         int timespan,
+                                         unsigned int index,
+                                         char* out,
+                                         unsigned int len);
 
 /**
  * Replaces `mars::xlog::appender_getfilepath_from_timespan()`: the log files
  * that *exist* for the day `timespan` days ago. Same `index` protocol as
- * mars_xlog_make_logfile_name.
+ * mars_xlog_make_logfile_name_instance.
  */
-int mars_xlog_getfilepath_from_timespan(int timespan,
-                                        const char* prefix,
-                                        const char* log_dir,
-                                        unsigned int index,
-                                        char* out,
-                                        unsigned int len);
-
-/* The cache directory, or a negative MARS_XLOG_ERR_* code. */
-int mars_xlog_current_log_cache_path(char* out, unsigned int len);
-
+int mars_xlog_getfilepath_from_timespan_instance(long long instance,
+                                                 int timespan,
+                                                 unsigned int index,
+                                                 char* out,
+                                                 unsigned int len);
+
+/* The directory the appender of `instance` is writing its files to, or a negative
+ * MARS_XLOG_ERR_* code. A directory and not a file, which is what the C++'s
+ * `XloggerAppender::GetCurrentLogPath` answers — `sg_logdir`. A handle no
+ * appender is open for — `0` among them, since no symbol of this ABI installs
+ * a process-wide one — answers MARS_XLOG_ERR_NO_PATH. */
+int mars_xlog_current_log_path_instance(long long instance, char* out, unsigned int len);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
 
 #endif /* MARS_XLOG_H_ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marsrs-react-native-xlog",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "React Native module for xlog, the logging half of mars-rs: a Rust implementation of Tencent/mars that writes the .xlog the C++ implementation produced.",
   "license": "MIT",
   "homepage": "https://github.com/orangeboyChen/mars-rs",

package/src/NativeXlog.ts

@@ -37,8 +37,32 @@ export interface Spec extends TurboModule {
    * holds. */
   getLevel(namePrefix: string): number;
 
-  /** `mars_xlog_flush_instance`. */
-  flush(namePrefix: string, sync: boolean): void;
+  /** `mars_xlog_request_flush_instance`: tells the writer thread it may take what is in
+   * the cache to the file, and returns at once — nothing waits, and nothing is
+   * in the file because this returned. */
+  requestFlush(namePrefix: string): void;
+
+  /** `mars_xlog_flush_now_instance`: the drain is the calling thread's, so the cache
+   * is in the log file, and the file's buffer is the OS's, when this returns. */
+  flushNow(namePrefix: string): void;
+
+  /** `flushNow` on a thread of the module's own, and a `Promise` settled when
+   * the drain is over: the one of the three that leaves the JS thread alone.
+   * A `Promise<void>` and not a `Promise` of a value — there is nothing to
+   * answer, only a drain to be over. */
+  flush(namePrefix: string): Promise<void>;
+
+  /** `mars_xlog_current_log_path_instance`: the directory this appender writes
+   * its files into, or `undefined` once it is closed. */
+  currentLogPath(namePrefix: string): string | undefined;
+
+  /** `mars_xlog_getfilepath_from_timespan_instance`: the day's files that are
+   * there — `0` is today, `1` is yesterday. */
+  logFiles(namePrefix: string, daysAgo: number): string[];
+
+  /** `mars_xlog_make_logfile_name_instance`: the day's names, whether or not the
+   * files are there yet. */
+  logFileNames(namePrefix: string, daysAgo: number): string[];
 
   /** `mars_xlog_set_level_instance`. */
   setLevel(namePrefix: string, level: number): void;
@@ -56,7 +80,8 @@ export interface Spec extends TurboModule {
   /** `mars_xlog_set_max_alive_duration_instance`. */
   setMaxAliveTime(namePrefix: string, seconds: number): void;
 
-  /** `mars_xlog_release_instance`: releases the appender `open` made. */
+  /** Releases the appender `open` made: by handle on iOS, by prefix on
+   * Android. */
   close(namePrefix: string): void;
 }
 

package/src/index.ts

@@ -37,7 +37,8 @@ export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 /** `TAppenderMode`: whether a record reaches the file before the call returns. */
 export const AppenderMode = {
   /** The record goes into the memory-mapped cache and a writer thread takes it
-   * to the file — what the C++ opens with, and what `flush` drains. */
+   * to the file — what the C++ opens with, and what `flushNow()` and
+   * `await flush()` drain. */
   async: 0,
   /** The record is in the file before the call returns, at a write and a lock
    * per line. */
@@ -62,15 +63,16 @@ export type CompressMode = (typeof CompressMode)[keyof typeof CompressMode];
  * gives it: what an `Xlog` is opened with.
  *
  * Every field has the default the C++'s own `XLogConfig` carries, so the one an
- * app has to give is `logDir` — the appender answers
- * `MARS_XLOG_ERR_EMPTY_LOG_DIR` without it. */
+ * app has to give is `logDir` — the C ABI opens no appender
+ * without it. */
 export interface XlogConfig {
   /** Where the log files are written; created if it is missing, and the one
    * field with no default. */
   logDir: string;
   /** What every log file starts with (`marsrs_20260927.xlog`), and the name the
    * appender is known by — an app that writes through two of them gives them
-   * two. `xlog` when left out. */
+   * two. `xlog` when left out, when handed over empty, and when what was
+   * handed over is nothing but whitespace. */
   namePrefix?: string;
   /** The level the appender is opened at; `info` when left out. */
   level?: LogLevel;
@@ -89,9 +91,29 @@ export interface XlogConfig {
 }
 
 /** `XlogConfig.namePrefix` of the Kotlin and of the Swift: what an appender is
- * opened with when a caller gives none. */
+ * opened with when a caller gives none — and when it gives a blank one, which
+ * the two halves do not agree about: the Kotlin answers its own default for a
+ * prefix of nothing but whitespace, and the Swift opens that prefix as it is.
+ * Naming the default here is what keeps the `Xlog` an app holds and the
+ * appender the halves hold the same one, whichever half it is — a prefix of
+ * spaces that one half substituted and the other did not is an appender this
+ * `Xlog` cannot ask about afterwards. */
 const DEFAULT_NAME_PREFIX = 'xlog';
 
+/** The shortest lifetime of a file the appender takes, in seconds: one below it
+ * — `0` among them — is refused, and the appender keeps the lifetime it had.
+ * `MIN_LOG_ALIVE_TIME` of the Rust, which is the one place the number is
+ * written down. */
+const MIN_ALIVE_TIME_SECONDS = 86400;
+
+/** The prefix an appender opened with `config` is known by: `namePrefix`, or
+ * [DEFAULT_NAME_PREFIX] when it is missing or blank. What is handed to the two
+ * halves is this and not the string the caller gave, so the two of them agree
+ * on one name for one appender. */
+function namePrefixOf(config: XlogConfig): string {
+  return config.namePrefix?.trim() || DEFAULT_NAME_PREFIX;
+}
+
 /** The appender of every `namePrefix` `Xlog.open` has opened and `close` has
  * not closed, by the prefix: what makes two `Xlog.open`s of one prefix one
  * appender, which the native side already is — one module, one appender per
@@ -125,7 +147,7 @@ export class Xlog {
   private open = true;
 
   private constructor(config: XlogConfig) {
-    this.namePrefix = config.namePrefix ?? DEFAULT_NAME_PREFIX;
+    this.namePrefix = namePrefixOf(config);
     this.currentLevel = config.level ?? LogLevel.info;
     this.currentMode = config.mode ?? AppenderMode.async;
   }
@@ -138,16 +160,25 @@ export class Xlog {
    * second one over the first would be a handle nothing releases. So two calls
    * of one prefix are one `Xlog`, and `close` on it is `close` on both.
    *
+   * The native side is asked either way, and not only the first time: one
+   * appender per prefix is one for the whole app, so one the app closed
+   * through its own Kotlin or Swift is gone from under this map, and asking
+   * again is what opens it again.
+   *
    * Throws when the appender would not take the configuration — an empty
-   * `logDir` or `namePrefix`, or a directory it cannot write to. */
+   * `logDir`, or a directory it cannot write to. */
   static open(config: XlogConfig): Xlog {
-    const namePrefix = config.namePrefix ?? DEFAULT_NAME_PREFIX;
+    const namePrefix = namePrefixOf(config);
     const alreadyOpen = openAppenders.get(namePrefix);
-    if (alreadyOpen) {
+    // The appender of a prefix is one for the whole process, so one another
+    // part of the app closed is gone from under this map: the open is asked
+    // again instead of trusted, and what it answers is the appender that is
+    // there now — the same one when nothing closed it.
+    if (alreadyOpen && NativeXlog.open({ ...config, namePrefix })) {
       return alreadyOpen;
     }
     const xlog = new Xlog(config);
-    if (!NativeXlog.open(config)) {
+    if (!NativeXlog.open({ ...config, namePrefix })) {
       throw new Error(
         `marsrs-react-native-xlog: the appender of '${xlog.namePrefix}' refused ${config.logDir}`
       );
@@ -219,11 +250,21 @@ export class Xlog {
       return;
     }
     NativeXlog.setMaxFileSize(this.namePrefix, bytes);
-    this.currentMaxFileSize = bytes;
+    // Mirrored once it is a size the native side took, and not before: that
+    // side reads a `number` as an `unsigned long long`, and a negative one or
+    // a `NaN` is not one it hands over. `0` is a size and not an absence —
+    // "never split" — so it is mirrored like any other.
+    if (Number.isFinite(bytes) && bytes >= 0) {
+      this.currentMaxFileSize = bytes;
+    }
   }
 
-  /** How long a log file is written to before the appender opens the next one,
-   * in seconds; `0` is the C++'s own ten days. */
+  /** How many seconds a log file of this appender is kept before the sweep
+   * deletes it — and not how long one is written to, which is what the day's
+   * turn and [maxFileSizeBytes] decide: `0` is the lifetime an appender
+   * opened with none keeps, the C++'s own ten days, and one below a day is a
+   * lifetime the appender refuses, so what this answers is the one it has and
+   * not the last one it was asked for. */
   get maxAliveTimeSeconds(): number {
     return this.currentMaxAliveTime;
   }
@@ -233,7 +274,12 @@ export class Xlog {
       return;
     }
     NativeXlog.setMaxAliveTime(this.namePrefix, seconds);
-    this.currentMaxAliveTime = seconds;
+    // Mirrored once it is a lifetime the appender took, and not before: a day
+    // is the shortest one it takes, and `0` is below it, so a mirror that took
+    // the number would answer a lifetime no appender is writing under.
+    if (seconds >= MIN_ALIVE_TIME_SECONDS) {
+      this.currentMaxAliveTime = seconds;
+    }
   }
 
   /** Whether a record at `level` is written: the appender's own answer, and the
@@ -288,17 +334,94 @@ export class Xlog {
     this.log(LogLevel.fatal, tag, message);
   }
 
-  /** `mars_xlog_flush_instance`: takes what is in the cache to the file. `sync`
-   * waits for the write, which is what an app wants before it reads the file,
-   * uploads it, or lets the process go. */
-  flush(sync = false): void {
+  /** `mars_xlog_request_flush_instance`: tells the writer thread it may take what is in
+   * the cache to the file, and returns at once. Nothing waits, and nothing is
+   * in the file because this returned — a record still in the cache is in a file
+   * the kernel holds, so one whose process dies keeps it. What it is for is a
+   * drain an app wants soon and does not want to wait for; before the file is
+   * read, uploaded or left behind, it is `flushNow()` or `await flush()`
+   * that an app wants and not this. */
+  requestFlush(): void {
+    if (!this.open) {
+      return;
+    }
+    NativeXlog.requestFlush(this.namePrefix);
+  }
+
+  /** `mars_xlog_flush_now_instance`: the drain is the calling thread's, so the
+   * records are in the log file — handed to the OS, and not left in the file's
+   * own `FILE*` — when it returns, and what that costs is the time the drain
+   * takes, on the thread that asked for it. It answers no `Promise` and takes
+   * no `await`, which is the point of it: the line after the call is a line
+   * that runs after the drain, and there is nothing to get wrong in between. */
+  flushNow(): void {
+    if (!this.open) {
+      return;
+    }
+    NativeXlog.flushNow(this.namePrefix);
+  }
+
+  /** `flushNow()` off the JS thread: the same drain, on a thread of the
+   * module's own, and a `Promise` that is settled when it is over. The records
+   * are on disk when it resolves, and what waited for them is that thread and
+   * not the one the app runs JS on — the call to make before reading or
+   * uploading a log file whose drain is longer than the app can sit through. */
+  async flush(): Promise<void> {
     if (!this.open) {
       return;
     }
-    NativeXlog.flush(this.namePrefix, sync);
+    await NativeXlog.flush(this.namePrefix);
   }
 
-  /** `mars_xlog_release_instance`: closes the appender `Xlog.open` made.
+  /** `mars_xlog_current_log_path_instance`: the directory this appender writes
+   * its files into, or `undefined` once it is closed.
+   *
+   * A directory and not a file, because that is what the C++'s
+   * `GetCurrentLogPath` answers, and there is no "not yet" state: an open
+   * appender has a directory from the moment it is opened. What an app that
+   * uploads a whole day asks for is [`logFiles`]. */
+  get currentLogPath(): string | undefined {
+    if (!this.open) {
+      return undefined;
+    }
+    return NativeXlog.currentLogPath(this.namePrefix);
+  }
+
+  /** `mars_xlog_getfilepath_from_timespan_instance`: the log files of `daysAgo`
+   * days ago that are *there* — what an app that uploads yesterday's opens. `[]`
+   * when the directory holds none of that day's. `0` is today, `1` is yesterday,
+   * and so on.
+   *
+   * This is a day of files and not the directory they are in: what
+   * `currentLogPath` answers is that, and this is this appender's own prefix and
+   * directory. */
+  logFiles(daysAgo: number): string[] {
+    if (!this.open) {
+      return [];
+    }
+    return NativeXlog.logFiles(this.namePrefix, daysAgo);
+  }
+
+  /** `mars_xlog_make_logfile_name_instance`: the paths of the log files of
+   * `daysAgo` days ago whether or not they are *there yet* — the name an app
+   * that is about to write, or that is naming a file to someone else, asks for.
+   *
+   * A day's answer can be two where [`logFiles`] answers one, when a cache dir
+   * is given and the file is there. */
+  logFileNames(daysAgo: number): string[] {
+    if (!this.open) {
+      return [];
+    }
+    return NativeXlog.logFileNames(this.namePrefix, daysAgo);
+  }
+
+  /** Closes the appender `Xlog.open` made. `mars_xlog_release_instance_of` on
+   * iOS, which is given the handle beside the prefix — a release by prefix
+   * alone closes whichever appender the prefix answers at that moment — and
+   * `mars_xlog_release_instance` on Android, which releases the prefix and is
+   * asked once per `Xlog`, by whichever takes its handle out of the table
+   * first.
+   *
    * Nothing is closed twice: an `Xlog` that is already closed answers `false`
    * from `isOpen` and drops what it is asked to write — and an appender two
    * names hold is closed for both, because `Xlog.open` gave them one `Xlog`. */