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

package/ios/Xlog.swift

@@ -1,4 +1,4 @@
-// The iOS half of `marsrs-react-native-xlog`: the eleven methods of the `Xlog`
+// The iOS half of `marsrs-react-native-xlog`: the sixteen methods of the `Xlog`
 // native module, each of them a straight call of a `mars_xlog_*` symbol — the
 // C ABI of `crates/marsrs-ffi`, in the `marsrs-xlog.xcframework` the pod carries.
 //
@@ -50,8 +50,10 @@ internal final class Xlog: NSObject {
     ///
     /// `false` is a configuration it refused — an empty `logDir` or
     /// `namePrefix`, or a directory it cannot write to — and it is what the JS
-    /// caller turns into a throw rather than a handle it would write through
-    /// the process-wide appender with.
+    /// caller turns into a throw rather than a handle nothing was opened
+    /// for. `true` for a prefix that is already open says which appender the
+    /// prefix has, and not that the configuration was taken again: the C ABI
+    /// answers the appender that is already there.
     @objc(open:)
     internal func openAppender(_ config: [AnyHashable: Any]) -> Bool {
         let logDir = string(config, "logDir")
@@ -61,14 +63,14 @@ internal final class Xlog: NSObject {
         let namePrefix = string(config, "namePrefix").isEmpty
             ? Self.defaultNamePrefix
             : string(config, "namePrefix")
-        // One appender per prefix: a prefix this module has already opened is
-        // answered as it is, and not opened again over the first, which would be
-        // a handle nothing releases. `src/index.ts` keeps the same map, so the
-        // two names an app holds for one prefix are one appender, and `close` on
-        // either is `close` on both.
-        guard handles[namePrefix] == nil else {
-            return true
-        }
+        // The C ABI is what keeps one appender per prefix: it answers the
+        // handle of the appender this prefix already has rather than opening a
+        // second one over its files, so asking again is how a prefix another
+        // part of the app closed is opened again — and the handle this stores
+        // is the one the registry answers, and not a dead one the last `open`
+        // left behind. `src/index.ts` keeps the same map, so the two names an
+        // app holds for one prefix are one appender, and `close` on either is
+        // `close` on both.
         let level = int(config, "level", Int32(MarsLevelInfo.rawValue))
         let mode = int(config, "mode", Int32(MarsAppenderAsync.rawValue))
         let compressMode = int(config, "compressMode", Int32(MarsCompressZlib.rawValue))
@@ -102,67 +104,161 @@ internal final class Xlog: NSObject {
     /// empty: there is no JS frame to name, and the C++ writes an empty one too.
     @objc(log:level:tag:message:)
     internal func log(_ namePrefix: String, level: Double, tag: String, message: String) {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix), let native = int32(level) else {
             return
         }
         tag.withCString { cTag in
             message.withCString { cMessage in
-                mars_xlog_write_instance(handle, Int32(level), cTag, nil, nil, 0, cMessage)
+                mars_xlog_write_instance(handle, native, cTag, nil, nil, 0, cMessage)
             }
         }
     }
 
+    /// `mars_xlog_current_log_path_instance`: the directory this appender
+    /// writes its files into, or `nil` once it is closed.
+    ///
+    /// A directory and not a file, because that is what the C++'s
+    /// `GetCurrentLogPath` answers; there is no "before the day's first record"
+    /// state, and the day's file is the question `logFiles` asks.
+    @objc(currentLogPath:)
+    internal func currentLogPath(of namePrefix: String) -> String? {
+        guard let handle = openHandle(of: namePrefix) else {
+            return nil
+        }
+        return path { out, len in
+            mars_xlog_current_log_path_instance(handle, out, len)
+        }
+    }
+
+    /// `mars_xlog_getfilepath_from_timespan_instance`: the log files of
+    /// `daysAgo` days ago that are *there* — what an app that uploads
+    /// yesterday's opens. `0` is today, `1` is yesterday, and so on.
+    @objc(logFiles:daysAgo:)
+    internal func logFiles(of namePrefix: String, daysAgo: Double) -> [String] {
+        dayPaths(of: namePrefix, daysAgo: daysAgo) { handle, timespan, index, out, len in
+            mars_xlog_getfilepath_from_timespan_instance(handle, timespan, index, out, len)
+        }
+    }
+
+    /// `mars_xlog_make_logfile_name_instance`: the paths of the log files of
+    /// `daysAgo` days ago, whether or not they are there yet.
+    @objc(logFileNames:daysAgo:)
+    internal func logFileNames(of namePrefix: String, daysAgo: Double) -> [String] {
+        dayPaths(of: namePrefix, daysAgo: daysAgo) { handle, timespan, index, out, len in
+            mars_xlog_make_logfile_name_instance(handle, timespan, index, out, len)
+        }
+    }
+
     /// `mars_xlog_is_enabled_for`: whether a record of the level would be
     /// written, which an app asks before it builds a message that is expensive
     /// to build.
     @objc(isLoggable:level:)
     internal func isLoggable(_ namePrefix: String, level: Double) -> Bool {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix), let native = int32(level) else {
             return false
         }
-        return mars_xlog_is_enabled_for(handle, Int32(level)) != 0
+        return mars_xlog_is_enabled_for(handle, native) != 0
     }
 
     /// `mars_xlog_get_level`: what the appender answers, and not what JS holds.
+    ///
+    /// Asked of the handle [openHandle] answered, and not of the one [handles]
+    /// cached: a prefix is one appender to the C ABI, so an appender another
+    /// part of the app closed — a `MarsRSXlog.Xlog` of the same prefix — took
+    /// it out of the registry and left the handle cached here, and
+    /// `mars_xlog_get_level` answers `-1` for a handle it does not know.
     @objc(getLevel:)
     internal func level(of namePrefix: String) -> Double {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix) else {
             return Double(MARS_LEVEL_NONE)
         }
-        return Double(mars_xlog_get_level(handle))
+        let native = mars_xlog_get_level(handle)
+        // A level `MarsLogLevel` does not carry — the `-1` above among them —
+        // is answered as `MARS_LEVEL_NONE` and not as it stands, which is the
+        // answer the Kotlin half of this module gives for the same numbers:
+        // `0`, `MarsLevelVerbose`, is the level that logs everything, so a
+        // level that is not one read as `0` is the opposite of what an
+        // appender that writes nothing was asked.
+        guard native >= 0, native <= MARS_LEVEL_NONE else {
+            return Double(MARS_LEVEL_NONE)
+        }
+        return Double(native)
     }
 
-    /// `mars_xlog_flush_instance`.
-    @objc(flush:sync:)
-    internal func flush(_ namePrefix: String, sync: Bool) {
-        guard let handle = handles[namePrefix] else {
+    /// `mars_xlog_request_flush_instance`: tells the writer thread it may take what is
+    /// in the cache to the log 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
+    /// an app wants before it reads the file or uploads it is `flushNow` or
+    /// `flush`.
+    @objc(requestFlush:)
+    internal func requestFlush(_ namePrefix: String) {
+        guard let handle = openHandle(of: namePrefix) else {
+            return
+        }
+        mars_xlog_request_flush_instance(handle)
+    }
+
+    /// `mars_xlog_flush_now_instance`: the drain is this 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 it costs is the time the drain takes,
+    /// on the JS thread and nowhere else.
+    @objc(flushNow:)
+    internal func flushNow(_ namePrefix: String) {
+        guard let handle = openHandle(of: namePrefix) else {
+            return
+        }
+        mars_xlog_flush_now_instance(handle)
+    }
+
+    /// `flushNow` off the JS thread: the same drain, on a queue of this
+    /// module's own, and `resolve` called when it is over.
+    ///
+    /// The handle and not `self`: the closure runs on another thread.
+    /// `resolve` and `reject` are `RCTPromiseResolveBlock` and
+    /// `RCTPromiseRejectBlock`, spelled out because the bridging header shows
+    /// this file the C ABI and nothing else — a TurboModule method codegen
+    /// answers a `Promise` from is given the two blocks and resolves one of
+    /// them, and there is nothing here that can fail, so `reject` is never
+    /// called.
+    @objc(flush:resolve:reject:)
+    internal func flush(
+        _ namePrefix: String,
+        resolve: @escaping (Any?) -> Void,
+        reject: @escaping (String?, String?, Error?) -> Void
+    ) {
+        guard let handle = openHandle(of: namePrefix) else {
+            resolve(nil)
             return
         }
-        mars_xlog_flush_instance(handle, sync ? 1 : 0)
+        Self.flushQueue.async {
+            mars_xlog_flush_now_instance(handle)
+            resolve(nil)
+        }
     }
 
     /// `mars_xlog_set_level_instance`.
     @objc(setLevel:level:)
     internal func setLevel(_ namePrefix: String, level: Double) {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix), let native = int32(level) else {
             return
         }
-        mars_xlog_set_level_instance(handle, Int32(level))
+        mars_xlog_set_level_instance(handle, native)
     }
 
     /// `mars_xlog_set_mode_instance`.
     @objc(setMode:mode:)
     internal func setMode(_ namePrefix: String, mode: Double) {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix), let native = int32(mode) else {
             return
         }
-        mars_xlog_set_mode_instance(handle, Int32(mode))
+        mars_xlog_set_mode_instance(handle, native)
     }
 
     /// `mars_xlog_set_console_log_instance`.
     @objc(setConsoleLogEnabled:enabled:)
     internal func setConsoleLogEnabled(_ namePrefix: String, enabled: Bool) {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix) else {
             return
         }
         mars_xlog_set_console_log_instance(handle, enabled ? 1 : 0)
@@ -173,36 +269,55 @@ internal final class Xlog: NSObject {
     /// 2^53.
     @objc(setMaxFileSize:bytes:)
     internal func setMaxFileSize(_ namePrefix: String, bytes: Double) {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix), let native = uint64(bytes) else {
             return
         }
-        mars_xlog_set_max_file_size_instance(handle, UInt64(bytes))
+        mars_xlog_set_max_file_size_instance(handle, native)
     }
 
     /// `mars_xlog_set_max_alive_duration_instance`.
     @objc(setMaxAliveTime:seconds:)
     internal func setMaxAliveTime(_ namePrefix: String, seconds: Double) {
-        guard let handle = handles[namePrefix] else {
+        guard let handle = openHandle(of: namePrefix), let native = int64(seconds) else {
             return
         }
-        mars_xlog_set_max_alive_duration_instance(handle, Int64(seconds))
+        mars_xlog_set_max_alive_duration_instance(handle, native)
     }
 
-    /// `mars_xlog_release_instance`: closes the appender `open` made.
+    /// `mars_xlog_release_instance_of`: closes the appender `open` made.
+    ///
+    /// The prefix is released only while the appender of it is still the one
+    /// `open` was answered with: a release is given a *prefix*, so one another
+    /// part of the app opened after this one was closed would be theirs and
+    /// would be closed by this. Naming the handle is what makes the question
+    /// and the release one call.
+    ///
+    /// Off the JS thread, the way `flush` is: a method codegen answers no
+    /// promise from is a call made on the JS thread, and a release is a drain
+    /// of everything the appender still holds and a write of the banner that
+    /// ends the file. The handle is taken out of `handles` here and not in the
+    /// block, so a reopen of the prefix that lands while the drain is queued
+    /// is a reopen of an appender this close never held.
     @objc(close:)
     internal func close(_ namePrefix: String) {
-        guard handles.removeValue(forKey: namePrefix) != nil else {
+        guard let handle = handles.removeValue(forKey: namePrefix) else {
             return
         }
-        namePrefix.withCString { mars_xlog_release_instance($0) }
+        Self.flushQueue.async {
+            namePrefix.withCString { prefix in
+                mars_xlog_release_instance_of(prefix, handle)
+            }
+        }
     }
 
     /// Closes what `open` opened and `close` was not asked about: the module
     /// goes away with the bridge, and an appender is a file its writer thread
     /// holds open.
     deinit {
-        for namePrefix in handles.keys {
-            namePrefix.withCString { mars_xlog_release_instance($0) }
+        for (namePrefix, handle) in handles {
+            namePrefix.withCString { prefix in
+                mars_xlog_release_instance_of(prefix, handle)
+            }
         }
         handles.removeAll()
     }
@@ -214,7 +329,12 @@ internal final class Xlog: NSObject {
     /// What the C++ passes on, which is the appender's own 6.
     private static let defaultCompressLevel: Int32 = 0
 
-    /// `0` keeps every log file, which is what the C++'s default is.
+    /// The queue `flush` drains on, and why it is one queue and not the JS
+    /// thread: a drain blocks the thread it runs on, and serial is what keeps
+    /// two drains of one appender from being two writers in one file.
+    private static let flushQueue = DispatchQueue(label: "io.github.orangeboychen.marsrs.reactnative.xlog.flush")
+
+    /// `0` keeps every cache file, which is what the C++'s default is.
     private static let keepEveryFile: Int32 = 0
 
     /// The four fields of `MarsXLogConfig` that are C strings, in the order the
@@ -227,6 +347,27 @@ internal final class Xlog: NSObject {
         case cacheDir = 3
     }
 
+    /// The handle [handles] holds for `namePrefix`, and `nil` when it is not
+    /// the appender of that prefix any more: the registry is asked, and the
+    /// handle it answers is the one that is open.
+    ///
+    /// The registry and not the handle alone, which is the question the Swift
+    /// `Xlog` of the port asks in its own `openHandle`:
+    /// `mars_xlog_release_instance` releases the appender of a *prefix* and
+    /// not of a handle, so a handle whose appender something else closed is
+    /// still the number this dictionary holds, and every symbol of the C ABI
+    /// answers a handle it does not know — `mars_xlog_get_level` with `-1`,
+    /// which is a level of no `MarsLogLevel`.
+    private func openHandle(of namePrefix: String) -> Int64? {
+        guard let handle = handles[namePrefix] else {
+            return nil
+        }
+        let owns = namePrefix.withCString { prefix in
+            mars_xlog_get_instance(prefix) == handle
+        }
+        return owns ? handle : nil
+    }
+
     /// Runs `body` with every one of `strings` as a C string, and frees the
     /// copies it made: `MarsXLogConfig` holds pointers rather than copies, and a
     /// Swift `String` has no C string of its own to hand out — `withCString` is
@@ -250,4 +391,89 @@ internal final class Xlog: NSObject {
     private func int(_ config: [AnyHashable: Any], _ key: String, _ fallback: Int32) -> Int32 {
         (config[key] as? NSNumber)?.int32Value ?? fallback
     }
+
+    /// What the caller sent for a level or a mode, and `nil` when it is not one:
+    /// a `Double`, because JS has one number type, and `Int32(_:)` traps on a
+    /// `NaN`, an infinity and a number out of `Int32`'s range — a trap on the
+    /// JS thread is the app dying, where a level nobody asked for is a record
+    /// that is not written. What it answers for a number with a fraction in it
+    /// is the number without one, which is the same truncation the Kotlin half
+    /// of this module does.
+    private func int32(_ value: Double) -> Int32? {
+        guard value.isFinite, value >= Double(Int32.min), value <= Double(Int32.max) else {
+            return nil
+        }
+        return Int32(value)
+    }
+
+    /// What the caller sent for a file size, and `nil` when it is not one: a
+    /// `UInt64` a `NaN`, a negative number or one above `UInt64.max` is not,
+    /// and `UInt64(_:)` traps on all three.
+    private func uint64(_ value: Double) -> UInt64? {
+        guard value.isFinite, value >= 0, value < 18446744073709551616.0 else {
+            return nil
+        }
+        return UInt64(value)
+    }
+
+    /// What the caller sent for a file lifetime, and `nil` when it is not one:
+    /// the same trap in `Int64(_:)`, and `0` is the lifetime an appender opened
+    /// with none keeps — the C++'s own ten days, and not one a setter can ask
+    /// for, since a lifetime below a day is refused — so a lifetime of `NaN`
+    /// was one the app never asked for rather than one it was told had been
+    /// refused.
+    private func int64(_ value: Double) -> Int64? {
+        guard value.isFinite,
+              value >= -9223372036854775808.0, value < 9223372036854775808.0 else {
+            return nil
+        }
+        return Int64(value)
+    }
+    /// What `read` writes into the buffer it is handed, as a string; `nil` when
+    /// it wrote nothing — a negative code, or a path of no length.
+    ///
+    /// A negative code is `nil` whatever it is, `MARS_XLOG_ERR_NO_SPACE` among
+    /// them: a path that does not fit 1024 bytes ends the walk the way the end
+    /// of the list does. A symbol that answers a length rather than a pointer
+    /// is the C ABI's way of saying the caller decides how much it can hold.
+    private func path(of read: (UnsafeMutablePointer<CChar>, UInt32) -> Int32) -> String? {
+        var buffer = [CChar](repeating: 0, count: 1024)
+        let written = read(&buffer, UInt32(buffer.count))
+        guard written > 0 else {
+            return nil
+        }
+        return String(cString: buffer)
+    }
+
+    /// The paths of one day, walked index by index until the symbol answers that
+    /// there is nothing at that index: the list the C++ fills a `std::vector`
+    /// with, asked one at a time.
+    ///
+    /// `daysAgo` is a `Double` because JS has one number type, and it is read
+    /// with [`int32`] and not `Int32(_:)`: the latter traps on a value it
+    /// cannot represent — `NaN`, `Infinity`, a number out of `Int32`'s range
+    /// — and a trap on the JS thread is the app dying, where a day nobody
+    /// asked for is an empty list. [`int32`] truncates a fraction the way the
+    /// Kotlin half of this module does, so `1.5` days ago is yesterday on both
+    /// of them and not yesterday on one and nothing on the other.
+    private func dayPaths(
+        of namePrefix: String,
+        daysAgo: Double,
+        at symbol: (Int64, Int32, UInt32, UnsafeMutablePointer<CChar>, UInt32) -> Int32
+    ) -> [String] {
+        guard let handle = openHandle(of: namePrefix), let timespan = int32(daysAgo) else {
+            return []
+        }
+        var walked: [String] = []
+        var index: UInt32 = 0
+        while let found = path(of: { out, len in
+            symbol(handle, timespan, index, out, len)
+        }) {
+            walked.append(found)
+            index += 1
+        }
+        return walked
+    }
+
+
 }

package/ios/include/mars_xlog.h

@@ -0,0 +1,242 @@
+/* Tencent is pleased to support the open source community by making Mars available.
+ * Copyright (C) 2016 THL A29 Limited, a Tencent company. All rights reserved.
+ *
+ * Licensed under the MIT License (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ * http://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is
+ * distributed on an "AS IS" basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+ * either express or implied. See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ * mars_xlog.h — C ABI of the Rust xlog implementation (`marsrs-ffi`).
+ *
+ * This header is the drop-in seam for the existing C++ / JNI / ObjC layers of
+ * Mars. It mirrors the C++ surface of
+ *
+ *     mars/xlog/appender.h            (mars::xlog::appender_open / flush / close ...)
+ *     mars/xlog/xlogger_interface.h   (mars::xlog::XloggerWrite / SetLevel ...)
+ *     mars/comm/xlogger/xloggerbase.h (TLogLevel)
+ *
+ * and is the C equivalent of the JNI bridge in mars/xlog/jni/Java2C_Xlog.cc.
+ *
+ * The header is hand-written and checked in next to the crate so that a C/C++
+ * 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. 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
+ * silently swallowed for the `void` symbols).
+ */
+
+#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). */
+typedef enum { MarsAppenderAsync = 0, MarsAppenderSync = 1 } MarsAppenderMode;
+
+/** Mirrors `mars::xlog::TCompressMode` (appender.h). */
+typedef enum { MarsCompressZlib = 0, MarsCompressZstd = 1 } MarsCompressMode;
+
+/** Mirrors `TLogLevel` (xloggerbase.h); `kLevelAll == kLevelVerbose == 0`. */
+typedef enum {
+    MarsLevelVerbose = 0,
+    MarsLevelDebug = 1,
+    MarsLevelInfo = 2,
+    MarsLevelWarn = 3,
+    MarsLevelError = 4,
+    MarsLevelFatal = 5
+} MarsLogLevel;
+
+/** Additional level understood only by the filter: disables every record. */
+#define MARS_LEVEL_NONE 6
+
+/* --- 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       */
+#define MARS_XLOG_ERR_BAD_COMPRESS (-3)  /* `compress_mode` outside MarsCompressMode */
+#define MARS_XLOG_ERR_EMPTY_LOG_DIR (-4) /* `log_dir` was NULL or ""              */
+#define MARS_XLOG_ERR_APPENDER (-5)      /* the Rust appender refused the config  */
+#define MARS_XLOG_ERR_NULL_OUT (-6)      /* `out` was NULL                        */
+#define MARS_XLOG_ERR_NO_SPACE (-7)      /* output buffer too small (0 or < need) */
+#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 */
+
+/* --- config ------------------------------------------------------------- */
+
+/**
+ * Mirrors `mars::xlog::XLogConfig` (appender.h) with C strings instead of
+ * `std::string`. Every pointer must be NUL-terminated UTF-8 or NULL; NULL is
+ * treated as "empty" (see the field docs) except for `log_dir`, which is
+ * mandatory.
+ */
+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; "" 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)          */
+    const char* cache_dir; /* NULL / "" => the mmap cache lives in log_dir   */
+    int cache_days;        /* < 0 => 0; 0 => keep every file                 */
+} MarsXLogConfig;
+
+/* ---- logger instances (mars::xlog::NewXloggerInstance and friends) ----
+ *
+ * Each instance owns an appender: its own log directory, prefix, key, mode and
+ * 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. 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,
+                              const char* tag,
+                              const char* filename,
+                              const char* func_name,
+                              int line,
+                              const char* log);
+
+/* 1 when the instance would write this level, 0 otherwise. */
+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: 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 / SetAppenderMode for an instance. */
+void mars_xlog_set_mode_instance(long long instance, int mode);
+
+/* 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". */
+void mars_xlog_set_max_file_size_instance(long long instance, unsigned long long bytes);
+
+/* 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_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. `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_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_instance.
+ */
+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.2",
+  "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",