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

package/ios/Frameworks/marsrs-xlog.xcframework/watchos-arm64-simulator/Headers/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/ios/Frameworks/marsrs-xlog.xcframework/watchos-arm64_arm64_32/Headers/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/ios/Xlog.mm

@@ -5,7 +5,7 @@
 // and jsi types. Neither has a Swift spelling: Swift's C++ interop stops at
 // templates and at the standard library. So what is here is the three things
 // React Native asks a module for and cannot read out of `Xlog.swift`, and the
-// eleven methods are there and not here.
+// sixteen methods are there and not here.
 //
 //   * `RCT_EXTERN_MODULE` registers the Swift class, which Swift cannot do for
 //     itself — registration is a constructor the runtime runs, and a Swift class
@@ -18,7 +18,7 @@
 //   * `methodQueue` answers `RCTJSThread`, the queue that is no queue: it is
 //     what makes a TurboModule's methods run on the JS thread, so a call is made
 //     where it is asked for and a method that answers a value answers it before
-//     it returns. Without it the eleven would be dispatched to a queue of the
+//     it returns. Without it the sixteen would be dispatched to a queue of the
 //     module's own and every answer would arrive as `undefined`.
 //
 // Objective-C++, and not Objective-C, because of the one `#include` a Swift