1.1--- a/lisp/ffi/rocksdb/merge.lisp Tue Aug 13 22:05:23 2024 -0400
1.2+++ b/lisp/ffi/rocksdb/merge.lisp Wed Aug 14 21:49:56 2024 -0400
1.3@@ -1,10 +1,40 @@
1.4 ;;; rocksdb/merge.lisp --- RocksDB Merge Operators
1.5
1.6-;;
1.7+;; RocksDB Lisp Merge Operator API
1.8+
1.9+;;; Commentary:
1.10+
1.11+;; When to use built-in ROCKSDB-MERGE:
1.12+
1.13+;; - You have data that needs to be incrementally updated.
1.14+
1.15+;; - You would usually need to read the data before knowing what the new value would be.
1.16+
1.17+;; Oterwise as far as the FFI is concerned - which doesn't support
1.18+;; AssociateMerge, you should use the Generic Merge API.
1.19+
1.20+;; When to use Associative Merge (unavailable in C/LISP API):
1.21+
1.22+;; - merge operands are formatted the same as Put values AND
1.23+
1.24+;; - it is okay to combine multiple operands into one
1.25+
1.26+;; When to use Generic Merge (this API):
1.27+
1.28+;; - you are unable to use Associate Merge
1.29+
1.30+;; - it is possible to combine multiple operands
1.31+
1.32+;;; Refs:
1.33+
1.34+;; impl: https://github.com/facebook/rocksdb/wiki/Merge-Operator-Implementation
1.35+
1.36+;; wiki: https://github.com/facebook/rocksdb/wiki/merge-operator
1.37
1.38 ;;; Code:
1.39 (in-package :rocksdb)
1.40
1.41+;; FullMerge() is used when a Put/Delete is the *existing_value (or null)
1.42 (define-alien-type rocksdb-full-merge-function
1.43 (function (* t)
1.44 (array unsigned-char)
1.45@@ -14,7 +44,7 @@
1.46 int
1.47 (array unsigned-char)
1.48 (* size-t)))
1.49-
1.50+;; PartialMerge() is used to combine two-merge operands (if possible)
1.51 (define-alien-type rocksdb-partial-merge-function
1.52 (function (* t)
1.53 (array unsigned-char)
1.54@@ -31,7 +61,7 @@
1.55 size-t))
1.56
1.57 (define-alien-type rocksdb-destructor-function
1.58- (function (* t)))
1.59+ (function void (* t)))
1.60
1.61 (define-alien-type rocksdb-name-function
1.62 (function c-string))
1.63@@ -40,7 +70,6 @@
1.64
1.65 ;; (sb-alien::define-alien-callable mangle int () 0)
1.66
1.67-;; (sb-alien::alien-callback
1.68 (define-alien-routine rocksdb-mergeoperator-create (* rocksdb-mergeoperator)
1.69 (state (* t))
1.70 (destructor (* rocksdb-destructor-function))
1.71@@ -61,17 +90,37 @@
1.72 (deftype rocksdb-mergeoperator-function ()
1.73 '(function (octet-vector (or octet-vector null) &rest t) (or null octet-vector)))
1.74
1.75+(define-alien-callable rocksdb-delete-value (* t)
1.76+ ((val (array unsigned-char))
1.77+ (vlen size-t))
1.78+ (declare (ignore val vlen))
1.79+ nil)
1.80+
1.81+(define-alien-callable rocksdb-destructor void ((self (* t)))
1.82+ (free-alien self))
1.83+
1.84+(define-alien-callable rocksdb-name c-string () (make-alien-string (symbol-name (gensym "rocksdb:"))))
1.85+
1.86 (define-alien-callable rocksdb-concat-full-merge (* t)
1.87- ((key (array unsigned-char)) (klen size-t)
1.88- (existing-val (array unsigned-char)) (existing-vlen size-t)
1.89- (ops (array (array unsigned-char))) (ops-length (* size-t)) (num-ops size-t)
1.90+ ((key (array unsigned-char))
1.91+ (klen size-t)
1.92+ (existing-val (array unsigned-char))
1.93+ (existing-vlen size-t)
1.94+ (ops (array (array unsigned-char)))
1.95+ (ops-length (* size-t))
1.96+ (num-ops size-t)
1.97 (success (array unsigned-char))
1.98 (new-vlen (* size-t)))
1.99+ (log:debug! (list key klen existing-val existing-vlen ops ops-length num-ops success new-vlen))
1.100 nil)
1.101
1.102 (define-alien-callable rocksdb-concat-partial-merge (* t)
1.103- ((key (array unsigned-char)) (klen size-t)
1.104- (ops (array (array unsigned-char))) (ops-length (* size-t)) (num-ops size-t)
1.105+ ((key (array unsigned-char))
1.106+ (klen size-t)
1.107+ (ops (array (array unsigned-char)))
1.108+ (ops-length (* size-t))
1.109+ (num-ops size-t)
1.110 (success (array unsigned-char))
1.111 (new-vlen (* size-t)))
1.112+ (log:debug! (list key klen ops ops-length num-ops success new-vlen))
1.113 nil)
