Audit exports. (#60)

Author: maleadt

README.md

@@ -56,7 +56,7 @@ close(d)
 using LMDB
 
 env = Environment("/tmp/mydb"; mapsize = 1<<30, maxreaders = 510,
-                               flags   = MDB_NOTLS | MDB_NORDAHEAD)
+                               flags   = LMDB.MDB_NOTLS | LMDB.MDB_NORDAHEAD)
 try
     start(env) do txn                                  # auto-commits/aborts
         open(txn) do dbi
@@ -70,7 +70,7 @@ try
     end
 
     # Cursor walk over the LMDB-owned mmap (zero-copy access).
-    start(env; flags = MDB_RDONLY) do txn
+    start(env; flags = LMDB.MDB_RDONLY) do txn
         open(txn) do dbi
             open(txn, dbi) do cur
                 LMDB.walk(cur, String, String) do k, v
@@ -87,7 +87,8 @@ end
 The package decodes `String`, `Vector{T}` for any bitstype `T`, and the
 primitive numeric types out of the box. To plug in a custom representation,
 define a `Base.read(io::IO, ::Type{T})` method; it will be picked up by `tryget`,
-`get`, `walk(f, cur, K, V)`, and the cursor accessors `key`/`value`/`item`.
+`get`, `walk(f, cur, K, V)`, and the cursor accessors
+`LMDB.key`/`LMDB.value`/`LMDB.item`.
 Status-code matchers live on `LMDBError`:
 
 ```julia

docs/src/man/cursors.md

@@ -11,7 +11,7 @@ scans, range queries, or to amortise the per-lookup overhead of
 ## Opening a cursor
 
 ```julia
-start(env; flags = MDB_RDONLY) do txn
+start(env; flags = LMDB.MDB_RDONLY) do txn
     open(txn) do dbi
         open(txn, dbi) do cur
             # use cur
@@ -48,16 +48,16 @@ seek_range!(cur, "users/", String)
 ## Reading at the current position
 
 ```julia
-key(cur, K)                   # current key, decoded as K
-value(cur, V)                 # current value, decoded as V
-item(cur, K, V)               # Pair{K, V}
+LMDB.key(cur, K)              # current key, decoded as K
+LMDB.value(cur, V)            # current value, decoded as V
+LMDB.item(cur, K, V)          # Pair{K, V}
 ```
 
 The defaults are `K = V = Vector{UInt8}`.
 
 ```julia
 seek_range!(cur, "users/", String) === nothing && return
-@show key(cur, String), value(cur, String)
+@show LMDB.key(cur, String), LMDB.value(cur, String)
 ```
 
 ## Range scans
@@ -66,12 +66,12 @@ A typical pattern for "all keys with a given prefix":
 
 ```julia
 prefix = "users/"
-start(env; flags = MDB_RDONLY) do txn
+start(env; flags = LMDB.MDB_RDONLY) do txn
     open(txn) do dbi
         open(txn, dbi) do cur
             k = seek_range!(cur, prefix, String)
             while k !== nothing && startswith(k, prefix)
-                v = value(cur, String)
+                v = LMDB.value(cur, String)
                 handle(k, v)
                 k = next!(cur, String)
             end
@@ -124,9 +124,9 @@ position:
 
 ```julia
 put!(cur, key, val)
-put!(cur, key, val; flags = MDB_NOOVERWRITE)
+put!(cur, key, val; flags = LMDB.MDB_NOOVERWRITE)
 delete!(cur)
-delete!(cur; flags = MDB_NODUPDATA)
+delete!(cur; flags = LMDB.MDB_NODUPDATA)
 ```
 
 `count(cur)` returns the number of duplicate values for the current
@@ -174,7 +174,7 @@ expensive. Park the txn with [`reset`](@ref Base.reset(::LMDB.Transaction))
 and refresh both the txn and the cursor with `renew(txn, cur)`:
 
 ```julia
-txn = start(env; flags = MDB_RDONLY)
+txn = start(env; flags = LMDB.MDB_RDONLY)
 cur = open(txn, dbi)
 while running
     ...                # use cur

docs/src/man/databases.md

@@ -13,7 +13,7 @@ to `Environment` to support multiple named sub-databases.
 ```julia
 dbi = open(txn)                      # main (unnamed) DB
 dbi = open(txn, "users")             # named sub-DB; needs maxdbs >= 1
-dbi = open(txn, "edges"; flags = MDB_CREATE | MDB_DUPSORT)
+dbi = open(txn, "edges"; flags = LMDB.MDB_CREATE | LMDB.MDB_DUPSORT)
 ```
 
 The do-block form closes the DBI on the way out:
@@ -69,7 +69,7 @@ tryget(txn, dbi, key,    UInt64)            # → Union{UInt64, Nothing}
 
 ```julia
 put!(txn, dbi, key, val)
-put!(txn, dbi, key, val; flags = MDB_NOOVERWRITE)
+put!(txn, dbi, key, val; flags = LMDB.MDB_NOOVERWRITE)
 delete!(txn, dbi, key)                       # → Bool: true if removed
 delete!(txn, dbi, key, val)                  # DUPSORT: delete one specific dup
 replace!(txn, dbi, key, val)                 # atomic put-and-return-old
@@ -89,7 +89,7 @@ Useful write flags:
 start(env) do txn
     open(txn) do dbi
         for (k, v) in sorted_pairs
-            put!(txn, dbi, k, v; flags = MDB_APPEND)
+            put!(txn, dbi, k, v; flags = LMDB.MDB_APPEND)
         end
     end
 end
@@ -131,8 +131,8 @@ live = (s.branch_pages + s.leaf_pages + s.overflow_pages) * s.psize
 ## Dropping a database
 
 ```julia
-drop(txn, dbi)                 # empty the DB (handle still valid)
-drop(txn, dbi; delete = true)  # delete the DB and close the handle
+LMDB.drop(txn, dbi)                 # empty the DB (handle still valid)
+LMDB.drop(txn, dbi; delete = true)  # delete the DB and close the handle
 ```
 
 For named sub-DBs, `delete = true` removes the entry from the env's

docs/src/man/dupsort.md

@@ -13,7 +13,7 @@ values" patterns.
 ```julia
 env = Environment("/tmp/edges"; mapsize = 1 << 30, maxdbs = 1)
 start(env) do txn
-    dbi = open(txn, "edges"; flags = MDB_CREATE | MDB_DUPSORT)
+    dbi = open(txn, "edges"; flags = LMDB.MDB_CREATE | LMDB.MDB_DUPSORT)
     put!(txn, dbi, "a", "b")
     put!(txn, dbi, "a", "c")
     put!(txn, dbi, "a", "d")

docs/src/man/environments.md

@@ -17,7 +17,7 @@ and `open`s the directory in one go:
 env = Environment("/tmp/mydb"; mapsize    = 1 << 30,   # 1 GiB virtual map
                                maxreaders = 510,
                                maxdbs     = 8,
-                               flags      = MDB_NOTLS)
+                               flags      = LMDB.MDB_NOTLS)
 ```
 
 If anything fails between `create` and a successful `open`, the
@@ -30,7 +30,7 @@ env = create()
 env[:MapSize] = 1 << 30
 env[:Readers] = 510
 env[:DBs]     = 8
-open(env, "/tmp/mydb"; flags = MDB_NOTLS)
+open(env, "/tmp/mydb"; flags = LMDB.MDB_NOTLS)
 ```
 
 The `[:Flags]`/`[:Readers]`/`[:MapSize]`/`[:DBs]` keys map directly to
@@ -46,7 +46,7 @@ The do-block constructor `environment(f, path; flags, mode)` opens the
 env, calls `f(env)`, and closes the env on the way out:
 
 ```julia
-environment("/tmp/mydb"; flags = MDB_NOTLS) do env
+environment("/tmp/mydb"; flags = LMDB.MDB_NOTLS) do env
     # use env
 end
 ```
@@ -68,7 +68,7 @@ end
 | `MDB_NOLOCK`     | the caller takes responsibility for locking |
 
 `MDB_RDONLY` can only be set at `open` time. Calling `set!(env,
-MDB_RDONLY)` on an open env will return `EINVAL`.
+LMDB.MDB_RDONLY)` on an open env will return `EINVAL`.
 
 ## Sizing the map
 

docs/src/man/essentials.md

@@ -84,7 +84,7 @@ when GC runs.
 The do-block constructors are usually what you want:
 
 ```julia
-environment("/tmp/mydb"; flags = MDB_NOTLS) do env
+environment("/tmp/mydb"; flags = LMDB.MDB_NOTLS) do env
     start(env) do txn
         open(txn) do dbi
             put!(txn, dbi, "k", "v")

docs/src/man/transactions.md

@@ -12,7 +12,7 @@ time per environment).
 
 ```julia
 txn = start(env)                          # read-write
-txn = start(env; flags = MDB_RDONLY)      # read-only
+txn = start(env; flags = LMDB.MDB_RDONLY)      # read-only
 ```
 
 LMDB can hold one writer plus an unlimited number of readers
@@ -48,7 +48,7 @@ Read-only txns are cheap to start and stop, but in a tight loop the
 pair is cheaper still:
 
 ```julia
-txn = start(env; flags = MDB_RDONLY)
+txn = start(env; flags = LMDB.MDB_RDONLY)
 for batch in batches
     open(txn) do dbi
         for k in batch
@@ -110,13 +110,13 @@ The most common patterns:
 
 ```julia
 # Hot read path: many small lookups, no writes
-start(env; flags = MDB_RDONLY) do txn ... end
+start(env; flags = LMDB.MDB_RDONLY) do txn ... end
 
 # Bulk import: single transaction across many writes (atomic, fast)
 start(env) do txn ... end
 
 # Long-running reader (e.g. background scrubber): reset + renew loop
-txn = start(env; flags = MDB_RDONLY)
+txn = start(env; flags = LMDB.MDB_RDONLY)
 while running
     ...
     reset(txn); renew(txn)

src/LMDB.jl

@@ -1,148 +1,36 @@
 module LMDB
 
 import Base: open, close, getindex, setindex!, put!, pop!, replace!, reset,
-             isopen, count, delete!, keys, get, show, show, stat, copy,
+             isopen, count, delete!, keys, get, show, stat, copy,
              empty!, length, isempty, iterate, haskey
 import Base.Iterators: drop
 
-export
-    # error type + matchers
-    LMDBError, is_notfound, is_keyexist, is_map_full,
-
-    # commonly-needed status codes
-    MDB_NOTFOUND, MDB_KEYEXIST, MDB_MAP_FULL,
-
-    # commonly-needed env flags
-    MDB_RDONLY, MDB_NOTLS, MDB_NORDAHEAD, MDB_NOSUBDIR,
-    MDB_NOSYNC, MDB_NOMETASYNC, MDB_WRITEMAP, MDB_NOMEMINIT,
-
-    # commonly-needed db flags
-    MDB_CREATE, MDB_DUPSORT, MDB_INTEGERKEY, MDB_REVERSEKEY,
-    MDB_DUPFIXED, MDB_INTEGERDUP, MDB_REVERSEDUP,
-
-    # commonly-needed write flags
-    MDB_NOOVERWRITE, MDB_NODUPDATA, MDB_APPEND, MDB_RESERVE,
-
-    # Julia wrappers: environment
-    Environment, create, environment,
-    sync, set!, unset!, info, stat, path, isopen, isflagset,
-    reader_check, reader_list,
-
-    # Julia wrappers: transaction
-    Transaction, start, abort, commit, reset, renew,
-
-    # Julia wrappers: database (DBI)
-    DBI, drop, get, put!, put_reserved!, delete!, tryget, replace!,
-
-    # Julia wrappers: cursor
-    Cursor, count, transaction, database,
-    seek!, seek_last!, seek_range!, next!, prev!,
-    key, value, item, walk,
-    seek_first_dup!, seek_last_dup!,
-    next_dup!, prev_dup!, next_nodup!, prev_nodup!,
-
-    # High-level interface
-    LMDBDict
-
-# ---------------------------------------------------------------------------
-# Error type. Defined here so the `@checked` macro can reference it; the
-# constructor itself defers to `errormsg` (defined after `liblmdb.jl` once
-# `mdb_strerror` is in scope).
-# ---------------------------------------------------------------------------
-
-"""LMDB exception type. `code` is the raw status code; use `is_notfound`,
-`is_keyexist`, `is_map_full` for common matches."""
-struct LMDBError <: Exception
-    code::Cint
-    msg::AbstractString
-    LMDBError(code::Integer) = new(Cint(code), errormsg(Cint(code)))
-    LMDBError(code::Integer, msg::AbstractString) = new(Cint(code), msg)
-end
-show(io::IO, err::LMDBError) = print(io, "Code[$(err.code)]: $(err.msg)")
-
-"Throw an `LMDBError` if `code` is non-zero. Returns `code` otherwise."
-@inline check(code) = iszero(code) ? code : throw(LMDBError(code))
-
-"""
-    is_notfound(err::LMDBError) -> Bool
-
-`true` if `err.code == MDB_NOTFOUND` (LMDB's "key not present" status).
-
-Use this to recover from a missing key when the lookup is not point-typed
-(otherwise `tryget` / `get(..., default)` are simpler):
-
-```julia
-try
-    LMDB.get(txn, dbi, "key", String)
-catch e
-    e isa LMDBError && is_notfound(e) || rethrow()
-    # treat as missing
+# `public name1, name2, ...` on 1.11+, no-op on 1.10.
+macro public(names)
+    @static if VERSION >= v"1.11"
+        syms = names isa Symbol ? (names,) :
+               Meta.isexpr(names, :tuple) ? names.args :
+               error("@public expects a symbol or a comma-separated list of symbols")
+        return esc(Expr(:public, syms...))
+    else
+        return nothing
+    end
 end
-```
-"""
-is_notfound
-
-"""
-    is_keyexist(err::LMDBError) -> Bool
-
-`true` if `err.code == MDB_KEYEXIST`. Raised by `put!` with `MDB_NOOVERWRITE`
-or `MDB_NODUPDATA` when the key (or duplicate) is already present.
-"""
-is_keyexist
-
-"""
-    is_map_full(err::LMDBError) -> Bool
 
-`true` if `err.code == MDB_MAP_FULL`. Raised when a write txn would exceed
-the environment's `MapSize`. The remedy is to grow `mapsize` (which can be
-done after `close(env)` without rewriting the database).
-"""
-is_map_full
+include("error.jl")
 
-# ---------------------------------------------------------------------------
-# C API: raw bindings, types, constants. Public-but-unexported.
-#
-# Every status-returning binding has a `@checked` wrapper (auto-throws) and an
-# `unchecked_*` companion (returns the raw `Cint` for callers that need to
-# inspect it, e.g. branching on `MDB_NOTFOUND`).
-#
-# Use as `LMDB.mdb_env_create`, `LMDB.MDB_NOTLS`, `LMDB.MDB_val`. The Julia
-# wrappers (`Environment`, `Transaction`, …) wrap these and are what most
-# callers should reach for.
-# ---------------------------------------------------------------------------
-
-include("checked.jl")
+# C API
 include("liblmdb.jl")
 
-"""Return a string describing a given LMDB status code."""
-errormsg(err::Cint) = unsafe_string(mdb_strerror(err))
-
-# Common status-code matchers, mirroring `is_notfound`/`is_keyexist` patterns.
-is_notfound(err::LMDBError) = err.code == MDB_NOTFOUND
-is_keyexist(err::LMDBError) = err.code == MDB_KEYEXIST
-is_map_full(err::LMDBError) = err.code == MDB_MAP_FULL
-
-# ---------------------------------------------------------------------------
-# ccall glue between the C API and the Julia wrappers: `MDBValue`, `MDBArg`,
-# and the `MDBValueIO <: IO` wrapper used to plug in custom decoders via
-# `Base.read(io, T)`.
-# ---------------------------------------------------------------------------
-
 include("common.jl")
 
-# ---------------------------------------------------------------------------
-# Julia wrappers around the raw bindings.
-# ---------------------------------------------------------------------------
-
+# Julia wrappers
 include("env.jl")
 include("txn.jl")
 include("dbi.jl")
 include("cur.jl")
 
-# ---------------------------------------------------------------------------
-# High-level interface: `LMDBDict`.
-# ---------------------------------------------------------------------------
-
+# High-level abstractions
 include("dicts.jl")
 
 end # module