diff --git a/.github/workflows/man-page-build-install.yml b/.github/workflows/man-page-build-install.yml index 3947a382..8a584eeb 100644 --- a/.github/workflows/man-page-build-install.yml +++ b/.github/workflows/man-page-build-install.yml @@ -87,6 +87,12 @@ jobs: repository: valkey-io/valkey-search path: valkey-search + - name: Checkout valkey-large-object + uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6 + with: + repository: valkey-io/valkey-large-object + path: valkey-large-object + - name: Checkout valkey-json uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6 with: @@ -111,6 +117,7 @@ jobs: VALKEY_BLOOM_ROOT=$GITHUB_WORKSPACE/valkey-bloom \ VALKEY_JSON_ROOT=$GITHUB_WORKSPACE/valkey-json \ VALKEY_SEARCH_ROOT=$GITHUB_WORKSPACE/valkey-search \ + VALKEY_LARGE_OBJECT_ROOT=$GITHUB_WORKSPACE/valkey-large-object \ -j; - name: Verify man pages build diff --git a/Makefile b/Makefile index 0c150b51..be5855d4 100644 --- a/Makefile +++ b/Makefile @@ -11,6 +11,7 @@ VALKEY_ROOT ?= ../valkey VALKEY_BLOOM_ROOT ?= ../valkey-bloom VALKEY_JSON_ROOT ?= ../valkey-json VALKEY_SEARCH_ROOT ?= ../valkey-search +VALKEY_LARGE_OBJECT_ROOT ?= ../valkey-large-object # Where to install man pages INSTALL_MAN_DIR ?= /usr/local/share/man @@ -45,6 +46,10 @@ ifeq ("$(wildcard $(VALKEY_SEARCH_ROOT))","") $(info Valkey Search variable pointed to nothing, skipping valkey-search commands) endif +ifeq ("$(wildcard $(VALKEY_LARGE_OBJECT_ROOT))","") + $(info Valkey Large Object variable pointed to nothing, skipping valkey-large-object commands) +endif + ifeq ("$(shell which pandoc)","") $(error Please install pandoc) endif @@ -73,10 +78,12 @@ commands_json_files = $(wildcard $(VALKEY_ROOT)/src/commands/*.json) bloom_commands_json_files = $(wildcard $(VALKEY_BLOOM_ROOT)/src/commands/*.json) valkey_json_commands_json_files = $(wildcard $(VALKEY_JSON_ROOT)/src/commands/*.json) valkey_search_commands_json_files = $(wildcard $(VALKEY_SEARCH_ROOT)/src/commands/*.json) +valkey_large_object_commands_json_files = $(wildcard $(VALKEY_LARGE_OBJECT_ROOT)/src/commands/*.json) existing_commands = $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md) \ $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md) \ $(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md) \ - $(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md) + $(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md) \ + $(valkey_large_object_commands_json_files:$(VALKEY_LARGE_OBJECT_ROOT)/src/commands/%.json=commands/%.md) topics = $(wildcard topics/*) commands = $(filter $(existing_commands),$(documented_commands)) @@ -91,7 +98,8 @@ json_for_documented_commands = \ $(patsubst commands/%.md,$(VALKEY_ROOT)/src/commands/%.json,$(filter $(commands_json_files:$(VALKEY_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \ $(patsubst commands/%.md,$(VALKEY_BLOOM_ROOT)/src/commands/%.json,$(filter $(bloom_commands_json_files:$(VALKEY_BLOOM_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \ $(patsubst commands/%.md,$(VALKEY_JSON_ROOT)/src/commands/%.json,$(filter $(valkey_json_commands_json_files:$(VALKEY_JSON_ROOT)/src/commands/%.json=commands/%.md),$(commands)))\ - $(patsubst commands/%.md,$(VALKEY_SEARCH_ROOT)/src/commands/%.json,$(filter $(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md),$(commands))) + $(patsubst commands/%.md,$(VALKEY_SEARCH_ROOT)/src/commands/%.json,$(filter $(valkey_search_commands_json_files:$(VALKEY_SEARCH_ROOT)/src/commands/%.json=commands/%.md),$(commands))) \ + $(patsubst commands/%.md,$(VALKEY_LARGE_OBJECT_ROOT)/src/commands/%.json,$(filter $(valkey_large_object_commands_json_files:$(VALKEY_LARGE_OBJECT_ROOT)/src/commands/%.json=commands/%.md),$(commands))) $(BUILD_DIR)/.commands-per-group.json: $(VALKEY_ROOT)/src/commands/. utils/build-command-groups.py | $(BUILD_DIR) utils/build-command-groups.py $(json_for_documented_commands) > $@~~ @@ -175,7 +183,7 @@ programs = $(progs:valkey-%=topics/%.md) configs = topics/valkey.conf.md # Define the base directories where valkey commands can come from -VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT) +VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT) $(VALKEY_LARGE_OBJECT_ROOT) man1_src = $(filter $(programs),$(topics_md)) man3_src = $(commands) @@ -205,7 +213,7 @@ $(MAN_DIR)/man1/valkey-%.1.gz: topics/%.md $(man_scripts) --version $(VERSION) --date $(DATE) \$< \ | utils/links-to-man.py - | $(to_man) > $@ $(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(BUILD_DIR)/.commands-per-group.json $(man_scripts) - $(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_JSON_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT)) + $(eval VALKEY_ROOTS := $(VALKEY_ROOT) $(VALKEY_JSON_ROOT) $(VALKEY_BLOOM_ROOT) $(VALKEY_SEARCH_ROOT) $(VALKEY_LARGE_OBJECT_ROOT)) $(eval FINAL_ROOT := $(firstword $(foreach root,$(VALKEY_ROOTS),$(if $(wildcard $(root)/src/commands/$*.json),$(root))))) $(if $(FINAL_ROOT),,$(eval FINAL_ROOT := $(lastword $(VALKEY_ROOTS)))) utils/preprocess-markdown.py --man --page-type command \ diff --git a/README.md b/README.md index 277b0fad..79132394 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,14 @@ This repo comes with a Makefile to build and install man pages. ```bash make VALKEY_ROOT=path/to/valkey VALKEY_BLOOM_ROOT=path/to/valkey-bloom \ VALKEY_JSON_ROOT=path/to/valkey-json VALKEY_SEARCH_ROOT=path/to/valkey-search \ + VALKEY_LARGE_OBJECT_ROOT=path/to/valkey-large-object \ sudo make install INSTALL_MAN_DIR=/usr/local/share/man ``` Prerequisites: GNU Make, Python 3, Python 3 YAML (pyyaml), Pandoc. Additionally, the scripts need access to the valkey code repo, where metadata files about the commands are stored. Additionally, -access to `valkey-bloom`, `valkey-json` and `valkey-search` repos is optional. +access to `valkey-bloom`, `valkey-json`, `valkey-search` and `valkey-large-object` repos is optional. The pages are generated under `_build/man/` by default. The default install location is `/usr/local/share/man` (in the appropriate subdirectories). diff --git a/commands/blob.info.md b/commands/blob.info.md new file mode 100644 index 00000000..ca3afd77 --- /dev/null +++ b/commands/blob.info.md @@ -0,0 +1,59 @@ +Returns metadata about the large object stored at `key`. +The command does not transfer the payload. + +If you do not give a field, the command returns all the fields as a flat array of field names and values. +If you give one field, the command returns only the value of that field. +The field name is not case-sensitive. + +The fields are: + +* `LEN` - The length of the object, in bytes, as the client stored it. + It does not include DRAM allocation overhead (`Dram` mode) or file system overhead (`Tiered` mode). +* `CRC` - The CRC32C (Castagnoli) checksum of the payload, as an unsigned 32-bit integer. + The server calculates this value when it stores the object. +* `TIER` - The storage tier of the object: `dram` or `disk`. + +In the `Dram` operating mode, `TIER` is always `dram`. +In the `Tiered` operating mode, `TIER` is `dram` only when a cached copy of the object is ready in DRAM. +Otherwise, `TIER` is `disk`. +For more information about the operating modes, see [Valkey Large Object - Overview](../topics/large-object.md). + +If `key` does not exist, the command returns nil. +If `key` holds a value of a different type, the command returns a `WRONGTYPE` error. + +Clients can compare `LEN` and `CRC` with the values that [`BLOB.RDMA_GET`](blob.rdma_get.md) returns, or with a checksum that they calculate after [`BLOB.TCP_GET`](blob.tcp_get.md). + +## Reply + +One of the following: + +* Array: when no field is given, a flat array of field names and values: `len` and the object length as an integer, `crc` and the CRC32C checksum as an integer, and `tier` and the storage tier (`dram` or `disk`). +* Integer: the object length in bytes when `LEN` is given, or the CRC32C checksum when `CRC` is given. +* `dram` or `disk`: the storage tier when `TIER` is given. +* Null: if the key does not exist. + +An error occurs if the field is not valid, if `largeobj.enabled` is `no`, or if the key holds a value of a different type. + +## Examples + +``` +127.0.0.1:6379> BLOB.TCP_SET mykey "hello world" +OK +127.0.0.1:6379> BLOB.INFO mykey +1) len +2) (integer) 11 +3) crc +4) (integer) 3381945770 +5) tier +6) dram +127.0.0.1:6379> BLOB.INFO mykey LEN +(integer) 11 +127.0.0.1:6379> BLOB.INFO mykey crc +(integer) 3381945770 +127.0.0.1:6379> BLOB.INFO mykey TIER +dram +127.0.0.1:6379> BLOB.INFO mykey SIZE +(error) ERR invalid information field +127.0.0.1:6379> BLOB.INFO nosuchkey +(nil) +``` diff --git a/commands/blob.rdma_get.md b/commands/blob.rdma_get.md new file mode 100644 index 00000000..ff6a3ad0 --- /dev/null +++ b/commands/blob.rdma_get.md @@ -0,0 +1,81 @@ +Writes the payload of the large object stored at `key` directly into client memory with RDMA. +The payload does not go through the Valkey connection. + +The connection must have an RDMA session. +To start a session, use [`BLOB.RDMA_HELLO`](blob.rdma_hello.md). + +Each `region` is a triple that identifies a client memory region that the client registered with its libfabric endpoint: + +* `rkey` - The remote key of the registered memory region. +* `addr` - The start address in the region. + This is a virtual address, or an offset into the registered memory when the fabric provider does not use virtual addresses. + `0` is a valid value. +* `len` - The number of bytes that the server can write into the region. + The value must be more than `0`. + +All values are unsigned decimal integers. +You can give up to 256 regions. +The server writes the object bytes into the regions in the order that you give them, and fills each region before it continues to the next one. + +The total length of all the regions must be equal to or more than the object length. +The regions can be larger than the object. +The reply gives the object length, so that the client knows where the valid data ends. + +The server replies only after all the RDMA writes are complete. +The reply is a two-element array: the object length in bytes, and the CRC32C (Castagnoli) checksum that the server stored for the object. +The client can calculate the checksum of the received bytes and compare it with this value. + +If `key` does not exist, the command returns nil. +The server looks up the key before it parses the regions and before it checks the session. +Thus, a missing key returns nil even when the connection has no RDMA session. +In `Tiered` mode, if too many disk operations run at the same time for the disk staging buffers, the command returns `ERR disk staging buffer pool exhausted; retry later`. +The error is temporary: a retry later can succeed, after operations in progress finish. +If `key` holds a value of a different type, the command returns a `WRONGTYPE` error. + +This is a blocking command, so it cannot run in transactions, scripts, functions, or module calls (see [Limitations](../topics/large-object.md#limitations)). + +To read the payload over TCP instead, use [`BLOB.TCP_GET`](blob.tcp_get.md). +To get only the length and checksum, use [`BLOB.INFO`](blob.info.md). +If the server cannot post the transfer for 1 second (for example, because the client endpoint is gone), the command fails with `ERR RDMA write failed`. +There is no other server-side timeout for the transfer. +To stop a transfer, close the connection. +For more information, see [Valkey Large Object - RDMA Transfers](../topics/large-object-rdma.md). + +## Reply + +One of the following: + +* Array: a two-element array, after all the RDMA writes are complete: the object length in bytes as an integer, and the CRC32C checksum of the object as an integer. +* Null: if the key does not exist. + +An error occurs if the memory regions are not valid or are too small for the object, if the connection has no RDMA session, if the RDMA write or a disk read fails, or if the key holds a value of a different type. See [Errors](../topics/large-object-rdma.md#errors) for all errors. + +## Examples + +You cannot do the transfer from `valkey-cli`. +The command needs a client that has a libfabric endpoint and registered memory, and that has an RDMA session on the connection. +The example shows the command shape and the reply. +In this example, the key holds a 1MB (1048576 bytes) object of zero bytes. +The first command writes the object into one region. +The second command writes the object into two regions of 512KB each. + +``` +127.0.0.1:6379> BLOB.RDMA_GET mykey 4242 140237318455296 1048576 +1) (integer) 1048576 +2) (integer) 338267154 +127.0.0.1:6379> BLOB.RDMA_GET mykey 4242 140237318455296 524288 4243 140237320552448 524288 +1) (integer) 1048576 +2) (integer) 338267154 +127.0.0.1:6379> BLOB.RDMA_GET mykey 4242 140237318455296 4096 +(error) ERR client memory address length 4096 smaller than object length 1048576 +127.0.0.1:6379> BLOB.RDMA_GET nosuchkey 4242 140237318455296 1048576 +(nil) +``` + +On a connection without an RDMA session, an existing key with regions that are large enough returns the session error. +The server checks the regions before the session: + +``` +127.0.0.1:6379> BLOB.RDMA_GET mykey 999 0 1048576 +(error) ERR no RDMA session (call BLOB.RDMA_HELLO first) +``` diff --git a/commands/blob.rdma_hello.md b/commands/blob.rdma_hello.md new file mode 100644 index 00000000..089b1c5f --- /dev/null +++ b/commands/blob.rdma_hello.md @@ -0,0 +1,67 @@ +Establishes an RDMA session for the current connection. +A client must send this command once on a connection before it can use [`BLOB.RDMA_SET`](blob.rdma_set.md) or [`BLOB.RDMA_GET`](blob.rdma_get.md) on that connection. + +`client-rdma-address` is the fabric address of the client endpoint, encoded as hexadecimal text. +The client gets this address from its libfabric endpoint. +When `largeobj.fabric-provider` is `EfaDirect`, the address must be exactly 32 bytes (64 hexadecimal characters). +When `largeobj.fabric-provider` is `Emulated`, the address must be a socket address: 16 bytes for IPv4 (`sockaddr_in`) or 28 bytes for IPv6 (`sockaddr_in6`). +The command takes exactly one argument. +With no argument or more than one argument, it returns an error. + +The server adds the client address to each of its fabric services. +The reply is an array with one hexadecimal fabric address for each server fabric service. +The client must add all the returned addresses to its own address vector before the first transfer. + +The session belongs to the connection. +The server removes the session when the connection closes. +A connection can have only one session: a second `BLOB.RDMA_HELLO` on the same connection returns an error. +To use a new client endpoint, open a new connection. + +If the RDMA fabric did not start on the server, the command returns an error. +In that case, only the TCP commands, [`BLOB.TCP_SET`](blob.tcp_set.md) and [`BLOB.TCP_GET`](blob.tcp_get.md), are available. + +For the full RDMA flow and the fabric configuration, see [Valkey Large Object - RDMA Transfers](../topics/large-object-rdma.md). + +## Reply + +Array of strings: one string for each server fabric service, with the hexadecimal fabric address of that service. + +An error occurs if RDMA is not available on the server, if the client address is not valid for the fabric provider, or if the connection already has an RDMA session. See [Errors](../topics/large-object-rdma.md#errors) for all errors. + +## Examples + +A useful `BLOB.RDMA_HELLO` needs a client that has a libfabric endpoint. +`valkey-cli` can send the command, but it cannot do the RDMA transfers that follow. +The example shows the command shape and the reply, with example addresses. + +``` +127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b2c3d4e5f60718293a4b5c6d7e8f900112233445566778899aabbccddeeff +1) "fe80000000000000049a1ffffe2b3c4d0b000000c5a3d1e20000000000000000" +2) "fe80000000000000049a1ffffe2b3c4e0c000000d7b4e2f30000000000000000" +127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b2c3d4e5f60718293a4b5c6d7e8f900112233445566778899aabbccddeeff +(error) ERR RDMA session already established +``` + +These errors do not need an RDMA client. +The server in this example uses the `EfaDirect` fabric provider: + +``` +127.0.0.1:6379> BLOB.RDMA_HELLO zz +(error) ERR invalid rdma address hex +127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b +(error) ERR rdma address must be 32 bytes +127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b extra +(error) ERR wrong number of arguments for 'BLOB.RDMA_HELLO' command +``` + +With the `Emulated` fabric provider, `valkey-cli` can open a session. +The reply has one address for each server fabric service, here one: + +``` +127.0.0.1:6379> BLOB.RDMA_HELLO 0a1b +(error) ERR rdma address is not a valid sockaddr +127.0.0.1:6379> BLOB.RDMA_HELLO 02001f907f0000010000000000000000 +1) "020098ff7f0000010000000000000000" +127.0.0.1:6379> BLOB.RDMA_HELLO 02001f907f0000010000000000000000 +(error) ERR RDMA session already established +``` diff --git a/commands/blob.rdma_set.md b/commands/blob.rdma_set.md new file mode 100644 index 00000000..f28eeb75 --- /dev/null +++ b/commands/blob.rdma_set.md @@ -0,0 +1,77 @@ +Stores a large object at `key`. +The server reads the payload directly from client memory with RDMA. +The payload does not go through the Valkey connection. + +The connection must have an RDMA session. +To start a session, use [`BLOB.RDMA_HELLO`](blob.rdma_hello.md). + +`total-len` is the length of the object in bytes. +The object must contain at least 1 byte. +The object length must not be more than the `largeobj.max-object-size` configuration (default 512MB). + +The optional `CRC` argument gives the CRC32C (Castagnoli) checksum of the payload, as an unsigned 32-bit decimal integer. +`CRC` must come directly after `total-len`. +When you give `CRC`, the server compares it with the checksum that it calculates after the transfer. +If the two values are different, the command returns an error and does not store the object. +The server always calculates the checksum and stores it with the object. + +Each `region` is a triple that identifies a client memory region that the client registered with its libfabric endpoint: + +* `rkey` - The remote key of the registered memory region. +* `addr` - The start address in the region. + This is a virtual address, or an offset into the registered memory when the fabric provider does not use virtual addresses. + `0` is a valid value. +* `len` - The number of bytes in the region. + The value must be more than `0`. + +All values are unsigned decimal integers. +You can give up to 256 regions. +The server reads `total-len` bytes from the regions in the order that you give them. +The total length of all the regions must be equal to or more than `total-len`. + +The server replies `OK` only after it reads all the bytes and stores the object. +In the `Tiered` operating mode, the server replies only after the disk write is complete. + +The overwrite, write-order, keyspace event, and eviction behavior is the same as for [`BLOB.TCP_SET`](blob.tcp_set.md). +If `key` holds a value of a different type, the command returns a `WRONGTYPE` error, and the server does not start a transfer. +The module does not replicate large objects or save their data to RDB or AOF. +This is a blocking command, so it cannot run in transactions, scripts, functions, or module calls. +For more information, see [Limitations](../topics/large-object.md#limitations). + +To read the object with RDMA, use [`BLOB.RDMA_GET`](blob.rdma_get.md). +For more information, see [Valkey Large Object - RDMA Transfers](../topics/large-object-rdma.md) and [Valkey Large Object - Configuration and Monitoring](../topics/large-object-configuration.md). + +## Reply + +`OK` after the server reads all the bytes and stores the object. + +An error occurs if an argument is not valid, if the connection has no RDMA session, if the RDMA read fails or the checksum is different from the `CRC` value, if there is not sufficient memory or disk space, or if the key holds a value of a different type. See [Errors](../topics/large-object-rdma.md#errors) for all errors. + +## Examples + +You cannot do the transfer from `valkey-cli`. +The command needs a client that has a libfabric endpoint and registered memory, and that has an RDMA session on the connection. +The example shows the command shape and the reply. +In this example, the client buffer holds 1MB (1048576 bytes) of zero bytes, with the CRC32C checksum `338267154`. + +``` +127.0.0.1:6379> BLOB.RDMA_SET mykey 1048576 4242 140237318455296 1048576 +OK +127.0.0.1:6379> BLOB.RDMA_SET mykey 1048576 CRC 338267154 4242 140237318455296 524288 4243 140237320552448 524288 +OK +127.0.0.1:6379> BLOB.INFO mykey +1) len +2) (integer) 1048576 +3) crc +4) (integer) 338267154 +5) tier +6) dram +127.0.0.1:6379> BLOB.RDMA_SET mykey 1048576 CRC 12345 4242 140237318455296 1048576 +(error) ERR CRC mismatch after transfer +127.0.0.1:6379> BLOB.RDMA_SET mykey 1048576 4242 140237318455296 1048576 4243 +(error) ERR memory address args must be rkey, addr, len triples +127.0.0.1:6379> BLOB.RDMA_SET mykey abc 4242 140237318455296 1048576 +(error) ERR invalid len +127.0.0.1:6379> BLOB.RDMA_SET mykey 1048576 CRC 4294967296 4242 140237318455296 1048576 +(error) ERR invalid CRC value +``` diff --git a/commands/blob.tcp_get.md b/commands/blob.tcp_get.md new file mode 100644 index 00000000..cba5b5e9 --- /dev/null +++ b/commands/blob.tcp_get.md @@ -0,0 +1,41 @@ +Returns the payload of the large object stored at `key`. +The server sends the payload inline in the reply, over the normal Valkey connection. + +If `key` does not exist, the command returns nil. +If `key` holds a value of a different type, the command returns a `WRONGTYPE` error. + +The reply does not include the checksum. +To get the length and the CRC32C checksum of the object, use [`BLOB.INFO`](blob.info.md). + +In the `Dram` operating mode, the server reads the object from DRAM. +In the `Tiered` operating mode, the server reads the object from the DRAM cache if a cached copy is ready. +Otherwise, the server reads the object from disk. +If too many disk operations run at the same time for the disk staging buffers, the command returns `ERR disk staging buffer pool exhausted; retry later`. +The error is temporary: a retry later can succeed, after operations in progress finish. +When an object gets sufficient reads, the server can copy it into the DRAM cache. +For the cache configuration, see [Valkey Large Object - Configuration and Monitoring](../topics/large-object-configuration.md). + +This is a blocking command, so it cannot run in transactions, scripts, functions, or module calls (see [Limitations](../topics/large-object.md#limitations)). + +To store an object over TCP, use [`BLOB.TCP_SET`](blob.tcp_set.md). +To write the payload directly into client memory with RDMA, use [`BLOB.RDMA_GET`](blob.rdma_get.md). + +## Reply + +One of the following: + +* String: the payload of the object. +* Null: if the key does not exist. + +An error occurs if a disk read fails, if `Tiered` mode has no free disk staging buffers, if the command runs in a transaction or a script, or if the key holds a value of a different type. See [Errors at run time](../topics/large-object-getting-started.md#errors-at-run-time) for all errors. + +## Examples + +``` +127.0.0.1:6379> BLOB.TCP_SET mykey "Hello, large object!" +OK +127.0.0.1:6379> BLOB.TCP_GET mykey +"Hello, large object!" +127.0.0.1:6379> BLOB.TCP_GET nosuchkey +(nil) +``` diff --git a/commands/blob.tcp_set.md b/commands/blob.tcp_set.md new file mode 100644 index 00000000..59e47b68 --- /dev/null +++ b/commands/blob.tcp_set.md @@ -0,0 +1,62 @@ +Stores a large object at `key`. +The client sends the payload inline in the command, over the normal Valkey connection. +The object length is the byte length of `value`. + +If `key` does not exist, the command creates it. +If `key` already holds a large object, the command replaces it, and the server frees the storage of the old object. +If `key` holds a value of a different type, the command returns a `WRONGTYPE` error and does not change the key. + +The object must contain at least 1 byte. +The object length must not be more than the `largeobj.max-object-size` configuration (default 512MB). +The object length is also limited by the core `proto-max-bulk-len` configuration (default 512MB). +For a larger value, the server replies `ERR Protocol error: invalid bulk length` and closes the connection. +For the size limits and the memory configuration, see [Valkey Large Object - Configuration and Monitoring](../topics/large-object-configuration.md). + +The server calculates a CRC32C (Castagnoli) checksum of the payload and stores it with the object. +Use [`BLOB.INFO`](blob.info.md) to read the length and the checksum. + +In the `Dram` operating mode, the server stores the object in DRAM and then replies. +In the `Tiered` operating mode, the server writes the object to a file in `largeobj.disk-dir`, and replies only after the disk write is complete. +If too many disk operations run at the same time for the disk staging buffers, the command returns `ERR disk staging buffer pool exhausted; retry later`. +This is a limit on concurrent disk operations, not a lack of DRAM for data. +The error is temporary: a retry later can succeed, after operations in progress finish. +Raise `largeobj.disk-staging-size` (needs a restart), lower `largeobj.max-buffers-per-op`, or send fewer concurrent disk operations. +When there is not sufficient space, the server can evict other large objects to make room, if the eviction configuration permits it. + +When two writes to the same key run at the same time, the write that the server received last is kept. +The server also replies `OK` to the write that it discards. + +After a successful write, the server publishes the keyspace event `largeobj.create` (new key) or `largeobj.update` (replaced key), of type module, when `notify-keyspace-events` includes module key type events (`d`). +The server does not publish an event when the write fails. + +The module does not replicate large objects or save their data to RDB or AOF. +This is a blocking command, so it cannot run in transactions, scripts, functions, or module calls. +For more information, see [Limitations](../topics/large-object.md#limitations). + +To read the object back over TCP, use [`BLOB.TCP_GET`](blob.tcp_get.md). +To send the payload with RDMA instead of inline in the command, use [`BLOB.RDMA_SET`](blob.rdma_set.md). + +## Reply + +`OK` after the server stores the object. + +An error occurs if the value is empty or larger than `largeobj.max-object-size`, if there is not sufficient memory or disk space, if a disk write fails, if the command runs in a transaction or a script, or if the key holds a value of a different type. See [Errors at run time](../topics/large-object-getting-started.md#errors-at-run-time) for all errors. + +## Examples + +``` +127.0.0.1:6379> BLOB.TCP_SET mykey "hello world" +OK +127.0.0.1:6379> BLOB.TCP_GET mykey +"hello world" +127.0.0.1:6379> BLOB.TCP_SET mykey "123456789" +OK +127.0.0.1:6379> BLOB.INFO mykey LEN +(integer) 9 +127.0.0.1:6379> BLOB.TCP_SET mykey "" +(error) ERR object length must be > 0 +127.0.0.1:6379> SET mystring "abc" +OK +127.0.0.1:6379> BLOB.TCP_SET mystring "hello world" +(error) WRONGTYPE Operation against a key holding the wrong kind of value +``` diff --git a/groups.json b/groups.json index 5bf1c08c..8bb391de 100644 --- a/groups.json +++ b/groups.json @@ -39,6 +39,10 @@ "display": "JSON", "description": "Operations on the JSON data type" }, + "large-object": { + "display": "Large object", + "description": "Operations on the large object data type" + }, "list": { "display": "List", "description": "Operations on the List data type" diff --git a/modules-nav/valkey-large-object.yml b/modules-nav/valkey-large-object.yml new file mode 100644 index 00000000..fbf2b2db --- /dev/null +++ b/modules-nav/valkey-large-object.yml @@ -0,0 +1,17 @@ +# Menu entries for the valkey-large-object module, merged into the core menu (nav.yml). +# An entry with "id" creates a new section. "after" places it after a section +# in the core menu; without it, the section goes at the end. +- id: large-object + title: Large object + after: data-types + landing: large-object + commands: [large_object] + topics: + - topic: large-object-getting-started + title: Getting started + - topic: large-object-use-cases + title: Use cases and examples + - topic: large-object-rdma + title: RDMA transfers + - topic: large-object-configuration + title: Configuration and monitoring diff --git a/modules.json b/modules.json index 3ef164fb..a670da5f 100644 --- a/modules.json +++ b/modules.json @@ -17,6 +17,15 @@ "description": "Module that allows users to use the JSON data type" }, + "valkey_large_object": { + "name": "valkey-large-object", + "repo": "https://github.com/valkey-io/valkey-large-object", + "description": "Module that allows users to use the large object data type", + "topic": "large-object", + "command_prefix": "blob.", + "version_notice": "valkey-large-object is at version 0.x. Commands, arguments, replies, and configuration can change before version 1.0." + }, + "valkey_ldap": { "name": "valkey-ldap", "repo": "https://github.com/valkey-io/valkey-ldap", diff --git a/topics/RDMA.md b/topics/RDMA.md index cca6e15b..44ff708d 100644 --- a/topics/RDMA.md +++ b/topics/RDMA.md @@ -6,6 +6,9 @@ description: Valkey Over RDMA experimental support Valkey supports the Remote Direct Memory Access (RDMA) connection type via a Valkey module that can be dynamically loaded on demand. +For bulk transfer of large objects between server memory and client memory with the large object module, see [Valkey Large Object - RDMA Transfers](large-object-rdma.md). +That module uses its own RDMA path, which is independent of the connection type on this page. + ## Getting Started [RDMA](https://en.wikipedia.org/wiki/Remote_direct_memory_access) diff --git a/topics/data-types.md b/topics/data-types.md index f55471bb..8c706fce 100644 --- a/topics/data-types.md +++ b/topics/data-types.md @@ -103,6 +103,17 @@ For more information, see: * [Bloom filter command reference](../commands/#bloom) * [Valkey-bloom module on GitHub](https://github.com/valkey-io/valkey-bloom/) +## Large Object + +[Large objects](large-object.md) are large binary values, such as machine learning KV cache blocks, tensors, and embeddings, stored in DRAM or in tiered DRAM and NVMe storage, with optional RDMA transfer to and from client memory. + +The large object data type / command support is provided by the `valkey-large-object` module, which is at version 0.x. +For more information, see: + +* [Overview of Large Objects](large-object.md) +* [Large object command reference](../commands/#large-object) +* [Valkey-large-object module on GitHub](https://github.com/valkey-io/valkey-large-object/) + ## Extensions To extend the features provided by the included data types, use one of these options: diff --git a/topics/large-object-configuration.md b/topics/large-object-configuration.md new file mode 100644 index 00000000..f9e05497 --- /dev/null +++ b/topics/large-object-configuration.md @@ -0,0 +1,247 @@ +--- +title: "Valkey Large Object - Configuration and Monitoring" +description: Configuration parameters, ACL category, and INFO fields of the Valkey Large Object module +--- + +> **Note:** [valkey-large-object](https://github.com/valkey-io/valkey-large-object) is at version 0.x. +> Commands, arguments, replies, and configuration can change before version 1.0. + +## Set configurations + +The configuration names have the `largeobj.` prefix, for example `largeobj.segment-size`. +Set the configurations when the module loads, with the full names. +Memory sizes can have units, such as `64mb` and `1gb`. + +In `valkey.conf`, put each configuration on its own line: + +``` +loadmodule /path/to/libvalkey_large_object.so +largeobj.operating-mode Dram +largeobj.segment-size 64mb +largeobj.max-object-size 32mb +``` + +On the command line: + +```bash +valkey-server --loadmodule /path/to/libvalkey_large_object.so \ + --largeobj.operating-mode Dram \ + --largeobj.segment-size 64mb \ + --largeobj.max-object-size 32mb +``` + +With [`MODULE LOADEX`](../commands/module-loadex.md): + +``` +MODULE LOADEX /path/to/libvalkey_large_object.so CONFIG largeobj.operating-mode Dram CONFIG largeobj.segment-size 64mb CONFIG largeobj.max-object-size 32mb +``` + +The configurations with `No` in the Mutable column can be set only when the module loads. +A lower `largeobj.max-object-size` does not change objects that are already stored. + +## Disk directory + +> **Warning:** In `Tiered` mode, the module deletes the `largeobj.disk-dir` directory and all its contents at startup and at shutdown, then creates it again, empty. +> Set `largeobj.disk-dir` to a new, empty directory that only this module uses, below the mount point (for example `/mnt/nvme/largeobj`). +> Never use a directory that has other data, or a mount point. + +## Configuration parameters + +This table shows the configurations that you are most likely to set. +For the full list, see the [module repository](https://github.com/valkey-io/valkey-large-object). + +| Name | Type | Default | Range | Mutable | Description | +|:-----|:-----|:--------|:------|:--------|:------------| +| `largeobj.operating-mode` | enum | `Dram` | `Dram`, `Tiered` | No | `Dram`: objects are in DRAM only. `Tiered`: objects are on NVMe and DRAM is a read cache. | +| `largeobj.disk-dir` | string | `""` | - | No | Directory for object files. Necessary in `Tiered` mode. Must be on XFS, the only supported file system, with `O_DIRECT` and user extended attributes, and a writable parent. **Deleted at startup and shutdown: see [Disk directory](#disk-directory).** | +| `largeobj.disk-dir-shards` | integer | `1024` | 1 to 65536 | No | `Tiered`: number of subdirectories of `largeobj.disk-dir` for the object files. More subdirectories let file creates and deletes run in parallel. | +| `largeobj.segment-size` | memory | `1gb` | 1mb to 1gb | No | Size of each DRAM pool segment and disk staging segment. Must be at least two times `largeobj.chunk-size`. The pool grows in segments; in `Tiered` mode it also shrinks. Each pool has at most 16384 segments: the DRAM pool stops at 16384 x `largeobj.segment-size`, and `largeobj.disk-staging-size` / `largeobj.segment-size` must not be more than 16384. | +| `largeobj.disk-staging-size` | memory | `1gb` | 1mb to 2^63-1 | No | `Tiered`: total size of the DRAM staging buffers for disk I/O. | +| `largeobj.disk-maxmemory` | memory | `0` | 0 to 2^63-1 | Yes | Maximum disk use in `largeobj.disk-dir`. Each file counts as its length rounded up to 4KB, or, on a striped XFS, to the stripe unit for files of at least one stripe unit. On XFS, each file also counts its inode. A file also counts the metadata blocks that it uses outside its inode (see `disk_metadata_spills`). `0` is unlimited. | +| `largeobj.max-object-size` | memory | `512mb` | 1 to 2^63-1 | Yes | Maximum object size for `BLOB.TCP_SET` and `BLOB.RDMA_SET`. `BLOB.TCP_SET` is also limited by the core `proto-max-bulk-len` (default 512MB). | +| `largeobj.max-promote-size` | memory | `256mb` | 0 to 2^63-1 | Yes | `Tiered`: maximum size of an object that is promoted from disk to DRAM. `0` disables promotion. | +| `largeobj.chunk-size` | memory | `1mb` | 4096 to 256mb | No | Chunk size for streaming I/O. Must be a multiple of 4096. | +| `largeobj.max-buffers-per-op` | integer | `64` | 2 to 1024 | Yes | Maximum number of `largeobj.chunk-size` buffers that one streaming operation holds. In `Tiered` mode, a lower value lets more disk operations share the disk staging buffers. | +| `largeobj.min-buffers-per-op` | integer | `2` | 1 to 1024 | Yes | `Tiered`: minimum number of `largeobj.chunk-size` buffers that a disk operation must get to start. If fewer buffers are free, the operation fails with `ERR disk staging buffer pool exhausted; retry later`. Must not be more than `largeobj.max-buffers-per-op`. | +| `largeobj.worker-threads` | integer | `8` | 1 to 32 | No | Number of worker threads for asynchronous I/O. | +| `largeobj.scaling-shrink-watermark` | integer (%) | `90` | 50 to 95 | Yes | Server `used_memory` / `maxmemory`, in percent, above which the DRAM pool does not expand. In `Tiered` mode, the pool also releases segments above this value (the objects stay on disk). | +| `largeobj.promote-min-hits` | integer | `1` | 1 to 255 | Yes | `Tiered`: number of disk reads of an object; the read that reaches this number promotes the object to DRAM. `1` promotes on the first read. | +| `largeobj.fabric-provider` | enum | `EfaDirect` | `EfaDirect`, `Emulated` | No | libfabric provider for RDMA. `EfaDirect`: EFA hardware (see [Providers](large-object-rdma.md#providers)). `Emulated`: libfabric over TCP sockets, for development and tests only. | +| `largeobj.fabric-interfaces` | string | `""` | - | No | Comma-separated list of fabric domains to use. Empty uses all domains that the provider finds. | +| `largeobj.fabric-crc-pool-threads` | integer | `2` | 1 to 1024 | No | Number of threads that calculate checksums for `BLOB.RDMA_SET` transfers. | +| `largeobj.max-rdma-registered-bytes` | memory | `380gb` | 0 to 2^63-1 | Yes | Maximum bytes of DRAM pool and disk staging segments that are registered with the fabric. The pool does not expand above this value. `0` is unlimited. No effect when the fabric is not available. | +| `largeobj.enabled` | bool | `yes` | `yes`, `no` | Yes | `no` rejects all large object commands with `DISABLED largeobj module is disabled`. Stored keys stay, and core commands such as `DEL` still work on them. | + +## Cross-configuration rules + +The module checks these rules when it loads. +It checks them again when `CONFIG SET` changes `largeobj.disk-maxmemory`, `largeobj.max-object-size`, `largeobj.max-promote-size`, `largeobj.max-buffers-per-op`, or `largeobj.min-buffers-per-op`. +If a rule is not satisfied, the module does not load, or `CONFIG SET` fails with the error in the table. + +| Rule | Mode | Error | +|:-----|:-----|:------| +| `largeobj.disk-maxmemory` is `0` or equal to or larger than `largeobj.max-object-size` | `Tiered` | `ERR largeobj.disk-maxmemory must be >= largeobj.max-object-size in Tiered mode` | +| `largeobj.disk-staging-size` is equal to or larger than `largeobj.segment-size` | `Tiered` | `ERR largeobj.disk-staging-size must be >= largeobj.segment-size` | +| `largeobj.segment-size` is equal to or larger than two times `largeobj.chunk-size` | All | `ERR largeobj.segment-size must be >= 2 * largeobj.chunk-size` | +| `largeobj.chunk-size` is a multiple of 4096 | All | `ERR largeobj.chunk-size must be a multiple of 4096` | +| `largeobj.max-buffers-per-op` is equal to or larger than `largeobj.min-buffers-per-op` | All | `ERR largeobj.max-buffers-per-op must be >= largeobj.min-buffers-per-op` | +| An object of `largeobj.max-object-size` fits in one segment | `Dram` | `ERR largeobj.segment-size is insufficient for largeobj.max-object-size` | +| An object of `largeobj.max-promote-size` fits in one segment | `Tiered` | `ERR largeobj.segment-size is insufficient for largeobj.max-promote-size` | + +An object "fits in one segment" when its chunks, plus 4KB of overhead for each chunk, plus 4KB, are not larger than `largeobj.segment-size`. +Thus `largeobj.max-object-size` must be a little smaller than `largeobj.segment-size` in `Dram` mode. +For example, with 64MB segments and the default `largeobj.chunk-size`, the largest `largeobj.max-object-size` is 66842624 bytes (`largeobj.segment-size` minus 260KB). +In `Tiered` mode, `largeobj.max-promote-size` (default 256MB) must fit in one segment, with the same overhead as `largeobj.max-object-size` (with 64MB segments, at most 66842624). +The default values (`largeobj.segment-size` `1gb`, `largeobj.max-object-size` `512mb`, `largeobj.chunk-size` `1mb`) satisfy all rules. + +## Memory and eviction + +The DRAM limit is the core Valkey `maxmemory` setting, together with `largeobj.scaling-shrink-watermark`. +When the fabric is available, `largeobj.max-rdma-registered-bytes` also limits the DRAM pool. +The maximum number of segments also limits the DRAM pool (see `largeobj.segment-size` in [Configuration parameters](#configuration-parameters)). + +A write can evict other large objects to make space. +The core `maxmemory-policy` setting controls which objects the module can evict: + +* `allkeys-*` policies - any large object. +* `volatile-*` policies - only large object keys that have a TTL. +* `noeviction` - no object. + The write fails with an `OOM` error. + +The module evicts in least recently used (LRU) order for all policies. +A read and a TTL change count as a use. +For the `*-lfu`, `*-random`, and `volatile-ttl` policies, the module also uses LRU order, and the server log shows a warning. + +* `Dram` mode - Eviction occurs only when `maxmemory` is set. +* `Tiered` mode - Eviction removes object files when `largeobj.disk-maxmemory` is larger than `0`. + `maxmemory` is not necessary for disk eviction. + When the DRAM cache is full, the module drops cached copies with the lowest LFU score (demotion). + The objects stay on disk. + +An evicted key stays in the keyspace until the module deletes it, within a few milliseconds when the backlog is small. +Until then, a read returns nil, but `EXISTS` and `DBSIZE` still count the key. +`pending_evictions` shows how many evicted keys wait to be deleted. + +## ACL + +The module adds the ACL category `@largeobj`. +All large object commands are in this category, and no other commands are. + +| Command | @largeobj | @read | @write | @connection | @fast | +|:--------|:----------|:------|:-------|:------------|:------| +| `BLOB.TCP_SET` | y | | y | | y | +| `BLOB.TCP_GET` | y | y | | | y | +| `BLOB.RDMA_HELLO` | y | | | y | y | +| `BLOB.RDMA_SET` | y | | y | | y | +| `BLOB.RDMA_GET` | y | y | | | y | +| `BLOB.INFO` | y | y | | | y | + +For example, this user can use all large object commands on keys that start with `kv:`: + +``` +127.0.0.1:6379> ACL SETUSER cache-client on >password +@largeobj ~kv:* +OK +``` + +`DEL` and `UNLINK` are not in `@largeobj`, so a user that must delete large object keys also needs these commands, for example `+@largeobj +del +unlink`. + +To stop a user from using the module, remove the category from the user, for example `ACL SETUSER -@largeobj`. + +## Security + +* The TCP commands carry the object data on the normal Valkey connection. + If you use Valkey TLS, TLS also protects this data. +* The RDMA commands carry only the command, the key, the client memory regions, and the reply on the Valkey connection. + The object data moves directly between client memory and server memory over the fabric, not through the Valkey connection. + Valkey TLS does not protect this data, and the module does not encrypt it. +* In `Tiered` mode, the module does not encrypt the object files in `largeobj.disk-dir`. + If you need encryption at rest, use file system or disk encryption. +* For an RDMA transfer, the server reads or writes only the client memory regions that the command names, at the client endpoint of the session of that connection. +* The server registers its own memory for local access only. + A client cannot read or write server memory directly; the server starts every transfer. + +## What to watch + +The field names in this table are without the `largeobj_` prefix (see [INFO fields](#info-fields)). + +| Field | What it tells you | Action | +|:------|:------------------|:-------| +| `evictions` | Large object keys evicted to make space. | If it grows fast, add memory or disk, or store fewer objects. | +| `pending_evictions` | Evicted keys that the module did not delete yet. | If it stays high, the module cannot delete keys as fast as it evicts them. | +| `dram_pool_exhausted`, `disk_capacity_exceeded` | Writes that the module failed with `OOM`. A write that core Valkey rejects with `OOM` before the module runs is not counted. | Raise `maxmemory` or `largeobj.disk-maxmemory`, or use a `maxmemory-policy` that permits eviction. | +| `disk_staging_buffer_exhausted` | `Tiered` disk operations that failed because of too much concurrency. | Raise `largeobj.disk-staging-size`, lower `largeobj.max-buffers-per-op`, or send fewer concurrent operations. | +| `disk_write_errors`, `disk_read_errors` | Failed disk I/O. | Look at the server log and the disk health. | +| `rdma_read_errors`, `rdma_write_errors`, `crc_mismatch` | Failed RDMA transfers. | Look at the client: registered regions, endpoint, and checksum. | + +The core `evicted_keys` field in `INFO stats` does not count large objects that the module evicts. +The module deletes the evicted keys itself (with an unlink), not through core eviction. +Use `evictions` in `INFO largeobj` instead. + +## INFO fields + +Use `INFO largeobj` to see the module metrics. +When `largeobj.enabled` is `no` and no large objects are stored, `INFO largeobj` returns no sections. +Valkey adds the `largeobj_` prefix to each section name and field name, for example section `largeobj_core_metrics` and field `largeobj_num_objects`. +The tables below show the names without the prefix. +They show only the most important fields. +For the full list, see the [module repository](https://github.com/valkey-io/valkey-large-object). + +### `core_metrics` + +| Field | Description | +|:------|:------------| +| `num_objects` | Number of large objects. | +| `inflight_requests` | Number of large object commands that are in progress. | + +### `evictions` + +| Field | Description | +|:------|:------------| +| `evictions` | Number of objects evicted to make space for a write. `Tiered` cache drops are demotions and are not counted. | +| `pending_evictions` | Number of evicted keys that the module did not finish deleting. These keys read as missing. | + +### `dram` + +| Field | Description | +|:------|:------------| +| `dram_segments` | Number of DRAM pool segments. | +| `dram_allocated_bytes` | Bytes allocated in the DRAM pool. | +| `dram_capacity_bytes` | Pool capacity: (segments minus draining segments) multiplied by the segment size. | +| `dram_utilization_pct` | DRAM pool use in percent. | +| `dram_objects` | Number of objects in DRAM. | +| `cache_hits` | `Tiered` only: reads served from the DRAM cache. | +| `cache_misses` | `Tiered` only: reads served from disk. | +| `cache_promotions` | `Tiered` only: objects promoted to the DRAM cache. | +| `cache_demotions` | `Tiered` only: cached copies dropped from DRAM. | +| `dram_rdma_registered_segments` | DRAM pool segments registered with the fabric. `0` when the fabric is not available. | + +### `disk` + +This section is only in `Tiered` mode. + +| Field | Description | +|:------|:------------| +| `disk_used_bytes` | Bytes used in `largeobj.disk-dir`, counted as for `largeobj.disk-maxmemory`. | +| `disk_utilization_pct` | `disk_used_bytes` as a percent of `largeobj.disk-maxmemory`. `0.00` when `largeobj.disk-maxmemory` is `0`. | +| `disk_metadata_spills` | Number of object files that use disk blocks outside their inode, in addition to their data. For example, a file that has more extents than its inode can list uses one more block. These blocks count in `disk_used_bytes`. | + +### `rdma` + +| Field | Description | +|:------|:------------| +| `rdma_sessions` | Number of open RDMA sessions. | +| `rdma_read_bytes` | Bytes that the server read from client memory (`BLOB.RDMA_SET`). | +| `rdma_write_bytes` | Bytes that the server wrote into client memory (`BLOB.RDMA_GET`). | + +### `error_metrics` + +| Field | Description | +|:------|:------------| +| `disk_read_errors` | Failed disk reads. | +| `disk_write_errors` | Failed disk writes. | +| `rdma_read_errors` | Failed RDMA reads from client memory. | +| `rdma_write_errors` | Failed RDMA writes into client memory. | +| `dram_pool_exhausted` | Writes that could not get DRAM pool memory. | +| `disk_staging_buffer_exhausted` | `Tiered` disk reads and writes that failed with `ERR disk staging buffer pool exhausted; retry later`, because too many disk operations ran at the same time for the disk staging buffers. | +| `disk_capacity_exceeded` | Writes that failed because of `largeobj.disk-maxmemory`. | +| `crc_mismatch` | `BLOB.RDMA_SET` writes rejected because the `CRC` value did not agree. | diff --git a/topics/large-object-getting-started.md b/topics/large-object-getting-started.md new file mode 100644 index 00000000..c50015ae --- /dev/null +++ b/topics/large-object-getting-started.md @@ -0,0 +1,262 @@ +--- +title: "Valkey Large Object - Getting Started" +description: How to build, load, and try the Valkey Large Object module +--- + +> **Note:** [valkey-large-object](https://github.com/valkey-io/valkey-large-object) is at version 0.x. +> Commands, arguments, replies, and configuration can change before version 1.0. + +This page shows how to build the module from source, load it into Valkey, and run your first commands. + +## Requirements + +* Valkey - Valkey 8.0 or later. +* Linux on `x86_64` or `aarch64` - The module has no architecture-specific code. +* Linux 5.1 or later (`Tiered` mode only) - The module uses io_uring for disk I/O, with the operations `IORING_OP_READV`, `IORING_OP_WRITEV`, `IORING_OP_READ_FIXED`, and `IORING_OP_WRITE_FIXED`, and with registered buffers (`IORING_REGISTER_BUFFERS`). + These are in Linux 5.1 and later. +* Rust - A recent stable Rust toolchain with `cargo`, for example from [rustup](https://rustup.rs/). +* Build tools - `clang` and its development files (for example `libclang-dev`), `gcc`, `make`, `git`, and `pkg-config`. +* libfabric - libfabric 2.0 or later and its development files are necessary at build time, also when you use only TCP. + The module uses the libfabric 2.0 interface (symbol version `FABRIC_1.8`), and the build needs the header `rdma/fi_collective.h`. + An older libfabric, for example 1.8.0, fails. + The build finds libfabric with `pkg-config`; check with `pkg-config --modversion libfabric`. + If libfabric is in a different location, or the default libfabric is older than 2.0, set `PKG_CONFIG_PATH` to the `lib/pkgconfig` directory of the newer one. + Then also set `LD_LIBRARY_PATH` to its `lib` directory when you run `valkey-server` or `build.sh`. +* EFA (optional) - The default fabric provider, `EfaDirect`, uses Elastic Fabric Adapter (EFA) hardware for RDMA. + Without RDMA hardware, use the TCP commands. + To develop and test RDMA client code without RDMA hardware, set `largeobj.fabric-provider` to `Emulated` (see [Providers](large-object-rdma.md#providers)). +* Locked memory - The module registers (pins) each segment one time for each fabric domain, and one more time for io_uring in `Tiered` mode. + This counts against `RLIMIT_MEMLOCK`. + Set the limit to `unlimited` (for example `ulimit -l unlimited`, or `LimitMEMLOCK=infinity` in a systemd unit), or to at least the total segment bytes times the number of registrations. +* RDMA clients - The libfabric provider of the client must support RMA (`FI_RMA`) with remote read and remote write, and the client needs a locked-memory limit for its registered buffers (see [Roles](large-object-rdma.md#roles)). +* XFS (`Tiered` mode only) - XFS is the only supported file system for `largeobj.disk-dir`, for example XFS on a local NVMe disk. + The module needs `O_DIRECT` and user extended attributes (`user.*` attributes): it stores a small header for each object file in the `user.lobj` extended attribute. + Other file systems, for example ext4, are not supported, also when they have these features. + On such a file system, the module loads with a warning in the log. + The module does not check for `O_DIRECT` and extended attributes when it loads. + On a file system without them, every write fails with `ERR disk write failed`. + +## Build from source + +```bash +git clone https://github.com/valkey-io/valkey-large-object +cd valkey-large-object +cargo build --release +``` + +The build writes the module library to `target/release/libvalkey_large_object.so`. + +The repository also has a `build.sh` script. +`./build.sh build` runs format and lint checks, the release build, and the unit tests. +`./build.sh` with no arguments also runs the integration tests against a Valkey server. + +If `bindgen` cannot find the standard C headers (for example `stddef.h`), add the GCC include directory: + +```bash +BINDGEN_EXTRA_CLANG_ARGS="-I$(gcc -print-file-name=include)" cargo build --release +``` + +## Load the module + +Set the module configurations with their full `largeobj.` names after `--loadmodule`. +Memory sizes can have units, such as `64mb`. +To load the module from `valkey.conf` or with `MODULE LOADEX`, see [Set configurations](large-object-configuration.md#set-configurations). +For all parameters, see [Valkey Large Object - Configuration and Monitoring](large-object-configuration.md). + +### Dram mode + +This example loads the module in `Dram` mode with 64MB segments. +`largeobj.max-object-size` must fit in one segment, so this example sets it to 32MB. + +```bash +valkey-server --port 6379 \ + --maxmemory 4gb \ + --maxmemory-policy allkeys-lru \ + --loadmodule ./target/release/libvalkey_large_object.so \ + --largeobj.operating-mode Dram \ + --largeobj.segment-size 64mb \ + --largeobj.max-object-size 32mb +``` + +In `Dram` mode, `maxmemory` is the DRAM limit, and `largeobj.max-rdma-registered-bytes` and the maximum number of segments also limit the DRAM pool. +With `allkeys-lru`, a write evicts the least recently used large objects when the module is full, and does not fail with `OOM`. +See [Memory and eviction](large-object-configuration.md#memory-and-eviction). + +### Tiered mode + +> **Warning:** In `Tiered` mode, the module deletes the `largeobj.disk-dir` directory and all its contents at startup and at shutdown, then creates it again, empty. +> Set `largeobj.disk-dir` to a new, empty directory that only this module uses, below the mount point (for example `/mnt/nvme/largeobj`). +> Never use a directory that has other data, or a mount point. + +This example stores objects on NVMe in `/mnt/nvme/largeobj` and uses DRAM as a read cache. +It uses 64MB segments, a 32MB maximum object size and promotion size, a 10GB disk limit, and 64MB of disk staging buffers. + +```bash +valkey-server --port 6379 \ + --maxmemory 4gb \ + --maxmemory-policy allkeys-lru \ + --loadmodule ./target/release/libvalkey_large_object.so \ + --largeobj.operating-mode Tiered \ + --largeobj.disk-dir /mnt/nvme/largeobj \ + --largeobj.segment-size 64mb \ + --largeobj.max-object-size 32mb \ + --largeobj.max-promote-size 32mb \ + --largeobj.disk-maxmemory 10gb \ + --largeobj.disk-staging-size 64mb +``` + +The module puts the object files in `largeobj.disk-dir-shards` subdirectories of `largeobj.disk-dir` (default 1024, named `0000` to `03ff`), and makes these subdirectories when it starts. + +### Load failures + +The module does not load if a configuration value is out of range, if the cross-configuration rules are not satisfied, or if the storage cannot start (for example, in `Tiered` mode, a `largeobj.disk-dir` that the module cannot create or clean). +The server log shows the cause. + +These are log messages that you are most likely to see when the module does not load: + +| Log message | Cause and fix | +|:------------|:--------------| +| ``libfabric.so.1: version `FABRIC_1.8' not found`` | An older libfabric is loaded at run time. Set `LD_LIBRARY_PATH` to the `lib` directory of libfabric 2.0 or later. | +| `fatal error: fi_collective.h: No such file or directory` (at build time) | The libfabric that `pkg-config` finds is older than 2.0. Set `PKG_CONFIG_PATH` to a newer libfabric. | +| `largeobj.segment-size is insufficient for largeobj.max-object-size` or `largeobj.max-promote-size` | See [Cross-configuration rules](large-object-configuration.md#cross-configuration-rules). | +| `largeobj: startup failed to reset disk-dir : Device or resource busy (os error 16); aborting module load` | `Tiered` mode: `largeobj.disk-dir` is a mount point. The module deletes the contents of the mounted file system, then cannot remove the mount point. Use a dedicated subdirectory of the mount for `largeobj.disk-dir`. | +| `largeobj: startup failed to reset disk-dir : ; aborting module load`, with an error such as `Permission denied` or `Read-only file system` | `Tiered` mode: the module deletes and creates `largeobj.disk-dir` at startup, and it could not. Make the parent directory of `largeobj.disk-dir` and the file system writable by the server user. | +| `largeobj: startup failed to reset disk-dir : disk-dir is required in Tiered operating mode; aborting module load` | `Tiered` mode: `largeobj.disk-dir` is not set. Set `largeobj.disk-dir` to a directory on the disk. | +| `largeobj: storage init failed: failed to create disk-dir shards under : ` | `Tiered` mode: the module could not create the `largeobj.disk-dir-shards` subdirectories, for example because the file system is full or read-only. Free space or fix the mount. | +| `largeobj: storage init failed: disk-dir has a block size of B, which does not divide the 4096 B I/O alignment; ...` | `Tiered` mode: the file system block size does not divide 4096, for example 64KB blocks. The module cannot count disk use exactly, so it does not load. Put `largeobj.disk-dir` on a file system with a block size of 4096 B or less. | +| `largeobj: storage init failed: cannot read disk-dir XFS geometry: `, or `cannot open disk-dir : `, or `cannot statfs disk-dir : ` | `Tiered` mode: the module could not read the file system geometry that it needs to count disk use, so it does not load. Make sure that the mount is healthy and that the server can read `largeobj.disk-dir`. | +| `largeobj: storage init failed: too many segments (DRAM , NVMe ). Max 16384 per pool. Increase segment-size or decrease disk-staging-size` | `Tiered` mode: `largeobj.disk-staging-size` divided by `largeobj.segment-size` is more than 16384. Make `largeobj.segment-size` larger or `largeobj.disk-staging-size` smaller. | +| `IORING_REGISTER_BUFFERS failed: Cannot allocate memory (os error 12)` | `Tiered` mode: the locked-memory limit is too low. Raise `RLIMIT_MEMLOCK` (see [Requirements](#requirements)). | +| `EFA registration of segment at ... failed (fatal)` | The server aborts, because a segment cannot be registered with the fabric. Raise the locked-memory limit (`ulimit -l`, `LimitMEMLOCK`), or set a lower `largeobj.max-rdma-registered-bytes`. | + +If the fabric provider does not start, the module loads and only the TCP commands are available. +The server log then shows `largeobj: fabric unavailable, RDMA path disabled`. + +If `largeobj.disk-dir` is not on XFS, the module loads, and the log shows `largeobj: disk-dir is not on XFS; disk usage is charged in 4096 B blocks`. +Only XFS is supported. +If `largeobj.disk-dir` does not support `O_DIRECT` or user extended attributes, the module loads, but every `Tiered` write fails with `ERR disk write failed`. + +In `Tiered` mode, for all features the module needs an open-file limit of at least `2 x maxclients + 128 + largeobj.max-cached-fds`. +With the defaults (`maxclients` 10000, `largeobj.max-cached-fds` 16384), this is 36512. +Raise the limit with `ulimit -n` or `LimitNOFILE`, or set a lower `maxclients`. +With the default `largeobj.fd-reserve` value `Lenient`, the module also loads with a lower limit: + +* Below `2 x maxclients + 128`, the file descriptor cache is off. + With the default `maxclients` 10000, the log shows, for example, `fd placement and the fd cache are off; set LimitNOFILE to at least 20128 to turn them on`. +* Between that value and the full value, the file descriptor cache is smaller. + With `maxclients` 1000 and an open-file limit of 10240, the log shows, for example, `the fd cache holds 8112; set LimitNOFILE to at least 18512 to cache all`. + +With `largeobj.fd-reserve` set to `Strict`, the module does not load if the full limit is not available. + +### Errors at run time + +| Error | Cause and fix | +|:------|:--------------| +| `OOM command not allowed when used memory > 'maxmemory'.` | The DRAM pool is full, and eviction cannot free space. Use `allkeys-lru` or `volatile-lru`, or raise `maxmemory`. | +| `OOM command not allowed when used disk space > 'largeobj.disk-maxmemory'.` | `Tiered` mode: the disk limit is reached, and eviction cannot free space. Use a policy that permits eviction, or raise `largeobj.disk-maxmemory`. | +| `ERR disk staging buffer pool exhausted; retry later` | `Tiered` mode: too many concurrent disk operations for the disk staging buffers, not a lack of DRAM for data. A retry later can succeed. Raise `largeobj.disk-staging-size`, lower `largeobj.max-buffers-per-op`, or send fewer concurrent operations. | +| `ERR max object size exceeded` | The object is larger than `largeobj.max-object-size`. | +| `ERR failed to set key` | Rare: the server could not store the key after the write. Retry. | +| `ERR Protocol error: invalid bulk length`, and the connection closes | A `BLOB.TCP_SET` value is larger than the core `proto-max-bulk-len` (default 512MB). Raise `proto-max-bulk-len`, or use `BLOB.RDMA_SET`. | +| `ERR no RDMA session (call BLOB.RDMA_HELLO first)` | The connection has no RDMA session, for example a new connection after a cluster redirect. Send `BLOB.RDMA_HELLO` on it. | +| `ERR RDMA read failed`, `ERR RDMA write failed` | The transfer to or from client memory failed, for example because the client endpoint is gone or a region is not registered. | +| `ERR disk write failed`, `ERR disk read failed` | `Tiered` mode: disk I/O failed. Look at the server log. If every write fails, `largeobj.disk-dir` does not support `O_DIRECT` or user extended attributes. | +| `ERR command not allowed in MULTI, scripts or module calls` | The data commands are blocking commands. See [Limitations](large-object.md#limitations). | +| `DISABLED largeobj module is disabled` | `largeobj.enabled` is `no`. | + +## Verify the module + +Use `MODULE LIST` to make sure that the module is loaded. +The module name is `largeobj`. + +``` +127.0.0.1:6379> MODULE LIST +1) 1) "name" + 2) "largeobj" + 3) "ver" + 4) (integer) 1 + ... +``` + +To see the module commands, filter by the module ACL category: + +``` +127.0.0.1:6379> COMMAND LIST FILTERBY ACLCAT largeobj +1) "BLOB.TCP_SET" +2) "BLOB.TCP_GET" +3) "BLOB.RDMA_SET" +4) "BLOB.RDMA_GET" +5) "BLOB.INFO" +6) "BLOB.RDMA_HELLO" +``` + +The order of the list can be different. +`ver` is the version number that the module registers: 1 for version 0.1.0. + +## First commands + +Store a value, read it, and get its metadata with `valkey-cli`: + +``` +127.0.0.1:6379> BLOB.TCP_SET greeting hello +OK +127.0.0.1:6379> BLOB.TCP_GET greeting +"hello" +127.0.0.1:6379> BLOB.INFO greeting +1) len +2) (integer) 5 +3) crc +4) (integer) 2591144780 +5) tier +6) dram +127.0.0.1:6379> BLOB.INFO greeting LEN +(integer) 5 +127.0.0.1:6379> BLOB.TCP_GET missing +(nil) +``` + +The `crc` value is the CRC32C checksum of the bytes `hello`. + +To store a file as an object, use the `-x` option of `valkey-cli`, which reads the last argument from standard input: + +```bash +valkey-cli -x BLOB.TCP_SET model:embeddings:v1 < embeddings.bin +``` + +Look at the module metrics: + +``` +127.0.0.1:6379> INFO largeobj +# largeobj_core_metrics +largeobj_num_objects:1 +largeobj_inflight_requests:0 + +# largeobj_evictions +largeobj_evictions:0 +largeobj_pending_evictions:0 +... +``` + +Delete the object with the core `DEL` command: + +``` +127.0.0.1:6379> DEL greeting +(integer) 1 +127.0.0.1:6379> BLOB.INFO greeting +(nil) +``` + +## Unload and clean up + +You cannot unload the module with `MODULE UNLOAD`, because it registers a data type. +To remove the module, stop the server and start it again without the module. + +All large objects are lost when the server stops (see [Persistence behavior](large-object.md#persistence-behavior)). +In `Tiered` mode, the module deletes `largeobj.disk-dir` at shutdown, or at the next startup after the server stops unexpectedly (see [Disk directory](large-object-configuration.md#disk-directory)). + +## Next steps + +* [Valkey Large Object - Use Cases and Examples](large-object-use-cases.md) +* [Valkey Large Object - RDMA Transfers](large-object-rdma.md) +* [Valkey Large Object - Configuration and Monitoring](large-object-configuration.md) +* [Large object command reference](../commands/#large-object) diff --git a/topics/large-object-rdma.md b/topics/large-object-rdma.md new file mode 100644 index 00000000..d0ab33a7 --- /dev/null +++ b/topics/large-object-rdma.md @@ -0,0 +1,201 @@ +--- +title: "Valkey Large Object - RDMA Transfers" +description: How RDMA transfers work in the Valkey Large Object module +--- + +> **Note:** [valkey-large-object](https://github.com/valkey-io/valkey-large-object) is at version 0.x. +> Commands, arguments, replies, and configuration can change before version 1.0. + +The RDMA commands move object bytes between the server and client memory with [libfabric](https://ofiwg.github.io/libfabric/). +The value bytes do not go through the Valkey connection. +The Valkey connection carries only the command, the key, a list of memory regions, and a short reply. + +## Comparison with Valkey RDMA connections + +Valkey also has its own [RDMA support](RDMA.md), which is a connection type for the full RESP protocol. +The two features are different and independent. + +| | Valkey RDMA connection | Large object RDMA commands | +|:--|:--|:--| +| What RDMA carries | All commands and replies, in place of TCP | Only the object payload of `BLOB.RDMA_SET` and `BLOB.RDMA_GET` | +| Commands and replies | Over RDMA | Over the normal Valkey connection, usually TCP | +| How to turn it on | Load `valkey-rdma.so` with `bind` and `port` (see [RDMA support](RDMA.md)) | Load the module and set `largeobj.fabric-provider` | +| RDMA interface | RDMA verbs with reliable connection (RC) queue pairs | libfabric, with the `EfaDirect` or `Emulated` provider | +| Data movement | Each side writes the RESP byte stream into a receive buffer of the other side | The server does one-sided RDMA reads and writes between registered client memory and its DRAM segments | +| Session setup | RDMA connection setup and feature negotiation | `BLOB.RDMA_HELLO` one time on each Valkey connection | +| Payload checksum | Not part of the protocol | CRC32C of each object | +| Status | Experimental | Version 0.x; can change before version 1.0 | + +The module does not use the Valkey RDMA connection type. +The large object commands are not supported on a Valkey RDMA connection. + +## Roles + +The server is the RDMA initiator, and the client is passive during the transfer. + +* For [`BLOB.RDMA_GET`](../commands/blob.rdma_get.md), the server does RDMA writes (`fi_write`) into client memory. +* For [`BLOB.RDMA_SET`](../commands/blob.rdma_set.md), the server does RDMA reads (`fi_read`) from client memory. + +The client memory is memory that the client registers with its libfabric domain, usually host memory. +Client device memory, for example GPU memory (`FI_HMEM`), is not supported. + +Client requirements: + +* The libfabric provider of the client must support RMA (`FI_RMA`) with remote read and remote write, because the server reads from and writes into client memory. +* The client registers its buffers with `fi_mr_reg`, which counts against the locked-memory limit (`RLIMIT_MEMLOCK`) of the client process. + Set the client limit to at least the total size of its registered buffers, or to `unlimited`. + +The server registers only host memory. +When the module loads, it sets the libfabric environment variable `FI_HMEM` to `system`, unless `FI_HMEM` is already set. +Thus libfabric on the server does not start device memory interfaces, for example CUDA on a GPU host. + +## Session model + +An RDMA session belongs to one Valkey connection. +In cluster mode, a client that follows a `MOVED` or `ASK` redirect to another node must send `BLOB.RDMA_HELLO` on that connection first. +Else `BLOB.RDMA_SET` and `BLOB.RDMA_GET` fail with `ERR no RDMA session (call BLOB.RDMA_HELLO first)`. + +1. The client opens a libfabric endpoint and gets its endpoint address with `fi_getname`. +2. The client registers each buffer that it will use with `fi_mr_reg`. + Each registration gives a remote key (`rkey`). +3. The client sends [`BLOB.RDMA_HELLO`](../commands/blob.rdma_hello.md) with its endpoint address as a hexadecimal string, one time on the connection. +4. The server adds the client address to the address vector of each of its fabric services. + The reply is an array with one hexadecimal server address for each fabric service. +5. The client adds every returned server address to its own address vector with `fi_av_insert`. +6. The client sends `BLOB.RDMA_SET` and `BLOB.RDMA_GET` commands on the same connection. +7. The session ends when the connection closes. + +The session keeps only the address routing information. +It does not keep memory regions or remote keys. +The client sends the regions in each command, so it can use a different buffer for each request. + +A second `BLOB.RDMA_HELLO` on the same connection fails with `ERR RDMA session already established`. +To start a new session, open a new connection. + +The server does not check the session for a missing key. +Thus `BLOB.RDMA_GET` on a missing key returns nil also when the connection has no session. + +## HELLO handshake + +``` +BLOB.RDMA_HELLO client-rdma-address +``` + +* When `largeobj.fabric-provider` is `EfaDirect`, the decoded address must be exactly 32 bytes. +* When `largeobj.fabric-provider` is `Emulated`, the decoded address must be a socket address: 16 bytes for IPv4 (`sockaddr_in`) or 28 bytes for IPv6 (`sockaddr_in6`). + +``` +127.0.0.1:6379> BLOB.RDMA_HELLO +1) "" +2) "" +``` + +## Memory region triples + +`BLOB.RDMA_SET` and `BLOB.RDMA_GET` describe client memory as one or more triples: + +``` +rkey addr len [rkey addr len ...] +``` + +* `rkey` - the remote key from the client memory registration. +* `addr` - the address of the region in client memory. + This is a virtual address, or an offset in the registered buffer when the provider does not use virtual addresses (`FI_MR_VIRT_ADDR`). + `0` is a valid value. +* `len` - the length of the region in bytes. + `0` is not valid. + +All three values are unsigned decimal integers. +Hexadecimal and negative values are rejected. +The number of arguments after the fixed arguments must be a multiple of 3. +A command can have a maximum of 256 triples. + +The server fills or reads the regions in the order of the command. +A chunk of the object can continue from the end of one region into the next region. +Thus one object can span buffers on several devices, or several buffers on one device. + +## Length rules + +* The sum of all region lengths must be equal to or larger than the object length. + For `BLOB.RDMA_SET`, the object length is the `total-len` argument. + For `BLOB.RDMA_GET`, it is the length of the stored object. +* Surplus region space is permitted. + For `BLOB.RDMA_GET`, the reply gives the object length, which shows where the valid data ends. +* `total-len` must be larger than 0 and not larger than `largeobj.max-object-size`. + +## CRC behavior + +The server calculates a CRC32C (Castagnoli) checksum of the bytes of each stored object. + +* `BLOB.RDMA_SET` can include `CRC ` directly after `total-len`. + The keyword is not case-sensitive, and the value is an unsigned 32-bit decimal integer. + The server calculates the checksum of the bytes that it read. + If the two values are different, the command fails with `ERR CRC mismatch after transfer` and the server does not store the object. +* `BLOB.RDMA_GET` replies with a two-element array, `[obj_len, crc32c]`, after all RDMA writes are complete. + To make sure that the data is correct end to end, calculate the CRC32C of the first `obj_len` bytes in your regions and compare it with the reply. +* [`BLOB.INFO`](../commands/blob.info.md) returns the stored checksum with the `CRC` field. + +The `largeobj.fabric-crc-pool-threads` configuration sets the number of server threads that calculate checksums of the data that `BLOB.RDMA_SET` transfers. + +## Providers + +The `largeobj.fabric-provider` configuration selects the libfabric provider when the module loads. + +| Provider | Use | Address | +|:---------|:----|:--------| +| `EfaDirect` (default) | [Elastic Fabric Adapter (EFA)](https://aws.amazon.com/hpc/efa/) hardware RDMA | 32 bytes | +| `Emulated` | libfabric over TCP sockets, for development and tests only | 16 or 28 bytes (socket address) | + +Use `Emulated` to develop and test RDMA client code (the `BLOB.RDMA_*` flow) on a host without RDMA hardware. +It runs libfabric over TCP sockets, so it is not for production and it is not faster than `BLOB.TCP_SET` and `BLOB.TCP_GET`. +In production on hosts without RDMA hardware, use the TCP commands. +For a test on one host, you can also set `largeobj.fabric-interfaces` to `lo` to serve only on the loopback interface. + +If the provider does not start, the module loads and only the TCP commands are available. +`BLOB.RDMA_HELLO` then fails with `ERR RDMA provider unavailable on this instance`. + +## Multiple fabric interfaces + +A host can have more than one fabric interface (domain). +By default, the module starts one fabric service on each domain that the provider finds. +To use only some domains, set `largeobj.fabric-interfaces` to a comma-separated list of domain names. + +The `BLOB.RDMA_HELLO` reply has one server address for each fabric service. +The client must add all of them, because the server can send a transfer from any of its fabric services. +For each transfer, the server picks two fabric services at random and uses the one with fewer transfers in progress. + +At startup, the server log shows each service address as `largeobj: fabric service rdma address `. + +All DRAM pool segments, and in `Tiered` mode all disk staging segments, are registered with the fabric when the module starts and when the pool expands. +The `largeobj.max-rdma-registered-bytes` configuration (default 380GB) limits the total size of registered segments, so that the pool stays below the registration limit of the device. +The pool does not expand above this limit. +The `dram_rdma_registered_segments` field in `INFO largeobj` shows the number of registered DRAM pool segments. + +## Cancel and timeout + +If the server cannot post a transfer for 1 second (for example, because the client endpoint is gone), the command fails with `ERR RDMA read failed` or `ERR RDMA write failed`. +There is no other server-side timeout or abort for a transfer. +To stop a transfer, close the connection. +The client must keep its registered regions valid until it receives the reply. + +## Errors + +These are the RDMA errors that you are most likely to see. +For the full list, see the [module repository](https://github.com/valkey-io/valkey-large-object). + +| Error | Cause | +|:------|:------| +| `ERR RDMA provider unavailable on this instance` | The fabric did not start. | +| `ERR rdma address must be 32 bytes`, `ERR rdma address is not a valid sockaddr` | The `BLOB.RDMA_HELLO` address does not agree with the fabric provider. | +| `ERR RDMA session already established` | A second `BLOB.RDMA_HELLO` on the same connection. | +| `ERR no RDMA session (call BLOB.RDMA_HELLO first)` | `BLOB.RDMA_SET` or `BLOB.RDMA_GET` without a session. | +| `ERR memory address args must be rkey, addr, len triples` | The region arguments are not a multiple of 3. | +| `ERR client memory address length smaller than object length ` | The regions are too small for the object. | +| `ERR max object size exceeded` | `total-len` is larger than `largeobj.max-object-size`. | +| `ERR CRC mismatch after transfer` | The checksum of the transferred bytes is not equal to the `CRC` value. Nothing is stored. | +| `ERR RDMA read failed`, `ERR RDMA write failed` | An RDMA transfer from or into client memory failed. | + +Both commands return `WRONGTYPE` when the key holds a different data type. +`BLOB.RDMA_SET` can also return the same storage errors as [`BLOB.TCP_SET`](../commands/blob.tcp_set.md), for example the `OOM` errors. + +For the RDMA fields in `INFO largeobj`, see [What to watch](large-object-configuration.md#what-to-watch) and [`rdma`](large-object-configuration.md#rdma). diff --git a/topics/large-object-use-cases.md b/topics/large-object-use-cases.md new file mode 100644 index 00000000..f887be42 --- /dev/null +++ b/topics/large-object-use-cases.md @@ -0,0 +1,144 @@ +--- +title: "Valkey Large Object - Use Cases and Examples" +description: Common use cases and worked examples for the Valkey Large Object module +--- + +> **Note:** [valkey-large-object](https://github.com/valkey-io/valkey-large-object) is at version 0.x. +> Commands, arguments, replies, and configuration can change before version 1.0. + +This page shows common patterns for the large object module. +The TCP examples use `valkey-cli`. +The RDMA examples show the flow of an RDMA-capable client, because `valkey-cli` cannot do RDMA transfers. +See [Valkey Large Object - RDMA Transfers](large-object-rdma.md) for the details of each RDMA step. + +## Common use cases + +### Offload and share an LLM inference KV cache + +Large language model (LLM) inference engines calculate attention key/value tensors (the KV cache) for each prompt prefix. +When GPU memory is full, the engine discards blocks of this cache, and it must calculate them again when a similar prompt comes. +A cache connector in the inference engine can store the blocks in Valkey instead. +Other GPU servers that connect to the same Valkey nodes can then use the blocks again. + +A common key pattern is a hash of the token prefix and the model identity, for example `kv:::`. +With RDMA, the server writes each block directly into a registered host buffer of the inference engine. +GPU memory (`FI_HMEM`) is not supported as a client buffer. +To read more blocks in parallel, a client can send requests for different keys to many Valkey nodes at the same time. + +### Stage model weights, embeddings, and artifacts + +Many workers can need the same large artifact at the same time, for example model weight shards, embedding tables, or tokenizer files. +Load each shard into Valkey one time, and let the workers read it from Valkey. +Use `Tiered` mode when the total size of the artifacts is larger than the DRAM that you want to use. +Frequently read objects are then served from the DRAM cache. + +### Large blob cache in front of object storage + +Applications can put a cache in front of an object store for large immutable blobs, for example images, media segments, or data set files. +On a miss, the application reads the blob from the object store and writes it to Valkey with a TTL. +Later reads come from Valkey. +The module does not persist objects, so the object store stays the source of truth. + +## Example: store and read a blob over TCP + +Store a file, look at its metadata, and read it again: + +```bash +valkey-cli -x BLOB.TCP_SET artifact:tokenizer:v3 < tokenizer.json +valkey-cli BLOB.INFO artifact:tokenizer:v3 +``` + +Use the cache-aside pattern with a TTL. +In this example, the value `123456789` represents the bytes from the object store: + +``` +127.0.0.1:6379> BLOB.TCP_GET blob:images:4711 +(nil) +127.0.0.1:6379> BLOB.TCP_SET blob:images:4711 123456789 +OK +127.0.0.1:6379> EXPIRE blob:images:4711 3600 +(integer) 1 +127.0.0.1:6379> BLOB.INFO blob:images:4711 LEN +(integer) 9 +127.0.0.1:6379> TTL blob:images:4711 +(integer) 3600 +``` + +To make sure that a blob did not change, compare the CRC32C that your application calculates with the stored value: + +``` +127.0.0.1:6379> BLOB.INFO blob:images:4711 CRC +(integer) 3808858755 +``` + +In `Tiered` mode, `BLOB.INFO` shows where the object is now: + +``` +127.0.0.1:6379> BLOB.INFO artifact:tokenizer:v3 TIER +disk +127.0.0.1:6379> BLOB.TCP_GET artifact:tokenizer:v3 +"..." +127.0.0.1:6379> BLOB.INFO artifact:tokenizer:v3 TIER +dram +``` + +With the default `largeobj.promote-min-hits` (1), the first read promotes the object into the DRAM cache. +After the promotion is complete, `TIER` shows `dram`. +Objects larger than `largeobj.max-promote-size` stay on disk. + +## Example: KV cache blocks over RDMA + +This pseudo-flow shows how a cache connector can store and load KV cache blocks with RDMA. +`fi_*` are libfabric calls in the client. +`valkey.call` sends a Valkey command on one connection. + +``` +# One time for each Valkey connection +ep = fi_endpoint(...) +my_addr = fi_getname(ep) +servers = valkey.call("BLOB.RDMA_HELLO", hex(my_addr)) +for s in servers: + fi_av_insert(unhex(s)) + +# One time for each buffer (registration is expensive, so do it at startup) +# Host memory only: GPU memory (FI_HMEM) is not supported +mr = fi_mr_reg(buffer, buffer_size) +rkey = fi_mr_key(mr) + +# Save one block (the block is in buffer at offset off, size n) +crc = crc32c(buffer[off : off + n]) +valkey.call("BLOB.RDMA_SET", key, n, "CRC", crc, rkey, addr(buffer) + off, n) +# Reply "OK": the server has read all bytes and stored the object + +# Load one block into buffer at offset off +reply = valkey.call("BLOB.RDMA_GET", key, rkey, addr(buffer) + off, n) +if reply is nil: + # Cache miss: calculate the block again +else: + obj_len, crc = reply + # Optional end-to-end check + assert crc32c(buffer[off : off + obj_len]) == crc +``` + +One block can span several buffers. +Send one triple for each buffer, in the order of the bytes: + +``` +BLOB.RDMA_GET kv:m1:9f2c:layers-0-15 1001 140230000000000 4194304 1002 140230100000000 4194304 +``` + +The total length of the regions must be equal to or larger than the object. +If the reply is `[6291456, ]`, the first 4MB are in the first buffer and the remaining 2MB are at the start of the second buffer. + +## Tips + +* Send `BLOB.RDMA_HELLO` one time on each connection, and keep the connection open. + A connection pool with a session on each connection prevents a handshake on each request. +* Register buffers one time and use them again. + Memory registration is expensive. +* To send many large object commands together, use a [pipeline](pipelining.md). + The data commands are not permitted in transactions or scripts (see [Limitations](large-object.md#limitations)). +* Keep each object at or below `largeobj.max-object-size`. + Split larger data into more keys, for example one key for each layer range or each shard. +* Do not use large objects as the only copy of data. + The module has no persistence and no replication. diff --git a/topics/large-object.md b/topics/large-object.md new file mode 100644 index 00000000..f1546597 --- /dev/null +++ b/topics/large-object.md @@ -0,0 +1,181 @@ +--- +title: "Valkey Large Object - Overview" +description: Valkey Large Object Module Overview +--- + +> **Note:** [valkey-large-object](https://github.com/valkey-io/valkey-large-object) is at version 0.x. +> Commands, arguments, replies, and configuration can change before version 1.0. + +The [valkey-large-object](https://github.com/valkey-io/valkey-large-object) module (BSD-3-Clause) adds a data type and commands to store large binary values in Valkey. +Typical values are blocks of a machine learning KV cache, tensors, embeddings, and other blobs that are megabytes or larger in size. +The module keeps objects in DRAM, or in a tiered layout where NVMe holds each object and DRAM is a read cache. +Clients can transfer values over the normal Valkey connection (TCP), or over RDMA with [libfabric](https://ofiwg.github.io/libfabric/). +With RDMA, the server writes object bytes directly into client memory and reads them directly from client memory, for example with an Elastic Fabric Adapter (EFA) (see [Providers](large-object-rdma.md#providers)). + +The module registers with the name `largeobj`. +Its value type is `largeob-k`. + +## Key concepts + +### Operating modes + +The `largeobj.operating-mode` configuration selects one of two modes when the module loads. + +* `Dram` (default) - All objects are in a DRAM pool. + The pool is a set of pre-allocated segments. + The mode does no disk I/O. +* `Tiered` - The module writes each object to a file on NVMe in `largeobj.disk-dir`. + DRAM is a read cache. + By default, the first read of an object promotes it into DRAM (see `largeobj.promote-min-hits` and `largeobj.max-promote-size`). + When the cache is full, the module drops cached copies with the lowest LFU score. + The module uses io_uring with `O_DIRECT` for disk I/O. + +### Segments and maximum object size + +The module allocates memory in fixed-size segments (`largeobj.segment-size`, from 1MB to 1GB). +In `Dram` mode, an object must fit in a single segment. +Thus an object of `largeobj.max-object-size` bytes, plus a small overhead for each chunk, must fit in one segment, and the largest object in `Dram` mode is less than 1GB. +The module also divides objects into chunks (`largeobj.chunk-size`) for streaming I/O. +Each chunk adds a small allocation overhead in the segment. +Each pool has at most 16384 segments, so the DRAM pool does not grow past 16384 x `largeobj.segment-size` (1TB with 64MB segments), also when `maxmemory` is larger. + +The default `largeobj.max-object-size` is 512MB. +The smallest object is 1 byte. +See [Cross-configuration rules](large-object-configuration.md#cross-configuration-rules) for the rules that relate these values. + +### Transports + +* TCP - [`BLOB.TCP_SET`](../commands/blob.tcp_set.md) and [`BLOB.TCP_GET`](../commands/blob.tcp_get.md) send the value in the RESP command and reply. + These commands are always available and work with any Valkey client. +* RDMA - [`BLOB.RDMA_SET`](../commands/blob.rdma_set.md) and [`BLOB.RDMA_GET`](../commands/blob.rdma_get.md) send only the key and a list of client memory regions. + The server reads or writes the value bytes with libfabric. + The client must first open a session with [`BLOB.RDMA_HELLO`](../commands/blob.rdma_hello.md). + +If the fabric does not start, the module still loads, and only the TCP commands are available. +See [Valkey Large Object - RDMA Transfers](large-object-rdma.md) for the full RDMA model. + +### CRC32C checksum + +The server calculates a CRC32C (Castagnoli) checksum of each object when it stores the object. +[`BLOB.INFO`](../commands/blob.info.md) and [`BLOB.RDMA_GET`](../commands/blob.rdma_get.md) return this value. +On [`BLOB.RDMA_SET`](../commands/blob.rdma_set.md), a client can send its own CRC32C value. +The server then rejects the write if the checksum of the transferred bytes is different. + +## Supported commands + +* [`BLOB.TCP_SET`](../commands/blob.tcp_set.md) - stores an object that is sent in the command. +* [`BLOB.TCP_GET`](../commands/blob.tcp_get.md) - returns an object as a bulk string. +* [`BLOB.RDMA_HELLO`](../commands/blob.rdma_hello.md) - opens an RDMA session on the connection. +* [`BLOB.RDMA_SET`](../commands/blob.rdma_set.md) - stores an object that the server reads from client memory. +* [`BLOB.RDMA_GET`](../commands/blob.rdma_get.md) - writes an object into client memory. +* [`BLOB.INFO`](../commands/blob.info.md) - returns the length, CRC32C, and storage tier of an object. + +See the [complete list of large object commands](../commands/#large-object). + +Core commands also operate on large object keys. +`DEL`, `UNLINK`, overwrite, expiry, and eviction free the object storage in the background. +See [Core commands on large object keys](#core-commands-on-large-object-keys). +`MEMORY USAGE` counts the payload only when the payload is in DRAM. + +When `notify-keyspace-events` includes module key type events (`d`), the module sends `largeobj.create` when a write creates a key and `largeobj.update` when a write replaces a value. + +## Limitations + +The current version has these limitations: + +* No persistence. + The module does not save object data to RDB or AOF. + Objects do not survive a server restart. + In `Tiered` mode, the module deletes `largeobj.disk-dir` at startup and shutdown (see [Disk directory](large-object-configuration.md#disk-directory)). + See [Persistence behavior](#persistence-behavior). +* No replication. + Replicas are not supported for large object data. + See [Replication](#replication). +* In cluster mode, slots that have large object keys cannot move. + See [Cluster mode](#cluster-mode). +* `BLOB.TCP_SET`, `BLOB.TCP_GET`, `BLOB.RDMA_SET`, and `BLOB.RDMA_GET` are blocking commands, so they cannot run in transactions, scripts, functions, or module calls. +* The module cannot be unloaded with `MODULE UNLOAD`. + Restart the server to remove it. + To stop users from using the module without a restart, use ACLs, for example `ACL SETUSER -@largeobj` (see [ACL](large-object-configuration.md#acl)). +* Active defragmentation is not implemented for large object memory. +* RDMA transfers have no server-side timeout other than a 1-second limit to post a transfer (see [Cancel and timeout](large-object-rdma.md#cancel-and-timeout)). + +### Persistence behavior + +These operations work while large object keys exist, but they do not keep the object data: + +* `SAVE`, `BGSAVE`, `SHUTDOWN` with save points, and the automatic RDB snapshots save the key names without the object data. +* `BGREWRITEAOF` keeps no object data. + With `aof-use-rdb-preamble yes` (the default), the rewritten AOF has the key names, as with `SAVE`. + With `aof-use-rdb-preamble no`, it has no large object keys. +* When the server loads an RDB file (at startup, with `DEBUG RELOAD`, or on a replica full synchronization), each large object key reads as missing. + The module starts to delete these keys within `largeobj.scaling-poll-ms` (default 2.5 seconds) after the load. + With many keys, this can take longer. + Until then, `EXISTS` and `DBSIZE` still count them. + For example, `EXISTS` still returns `1` directly after a `BLOB.TCP_GET` of the key returns nil, and returns `0` a few seconds later. +* `DUMP` returns a value without the object data. + `RESTORE` of that value fails with `ERR Bad data format`, so `MIGRATE` fails (see [Cluster mode](#cluster-mode)). + +The server log shows a warning, for example `largeobj: persistence is not supported: blobs are saved to RDB/DUMP without their data`, the first time that each case occurs. + +### Replication + +The module does not replicate large objects: + +* A large object write on the primary is not sent to the replica. + The replica does not have the key. +* At a full synchronization, the replica loads the large object keys without their data. + They read as missing, and the replica deletes them a few seconds later, as after an RDB load. +* In that time, a `COPY` from the primary of such a key fails on the replica. + The replica log then shows `This replica is sending an error to its primary: 'module key failed to copy'`. +* If a replica becomes the primary, it has no large objects. + +### Cluster mode + +The module loads on each node of a cluster. +Each command uses a single key (or no key for `BLOB.RDMA_HELLO`), so cluster clients can route commands by slot. + +* An RDMA session belongs to one connection to one node. + Send `BLOB.RDMA_HELLO` on each connection to each node, and add the server addresses of each node to the address vector. + Each node replies with its own server addresses. +* You cannot move a slot that has large object keys. + `MIGRATE` uses `DUMP` and `RESTORE`, which do not keep object data. + The key stays on the source node: + + ``` + 127.0.0.1:7395> MIGRATE 127.0.0.1 7394 foo 0 5000 + (error) ERR Target instance replied with error: ERR Bad data format + ``` + + Atomic slot migration (`CLUSTER MIGRATESLOTS`) is refused with `ERR The module largeobj does not support atomic slot migrations. Please ensure all modules have declared support for atomic slot migration and try again`. +* To add capacity, raise `maxmemory` (`Dram` mode) or `largeobj.disk-maxmemory` (`Tiered` mode) on the nodes, if the hosts have the memory or disk. + Both are mutable with `CONFIG SET`. + Else move a slot to a new node only when the slot has no large object keys: delete the large object keys in the slot first (or let them expire), move the slot, and then write the objects again. + Or make a new, larger cluster and write the objects to it. +* After a `MOVED` or `ASK` redirect, the client sends the command on a connection to the other node. + If that connection has no RDMA session, `BLOB.RDMA_SET` and `BLOB.RDMA_GET` fail with `ERR no RDMA session (call BLOB.RDMA_HELLO first)`. + Send `BLOB.RDMA_HELLO` on that connection first. + +### Core commands on large object keys + +These results are the same in `Dram` and `Tiered` mode. + +| Command | Result | +|:--------|:-------| +| `COPY` | Works. The copy has its own data. | +| `RENAME`, `RENAMENX` | Work. | +| `MOVE`, `SWAPDB` | Work. | +| `EXPIRE`, `PEXPIRE`, `TTL`, `PERSIST` | Work. | +| `TYPE` | Returns `largeob-k`. | +| `OBJECT ENCODING` | Returns `raw`. | +| `DUMP` | Returns a value without the object data. | +| `RESTORE` | Fails with `ERR Bad data format`. | +| `DEL`, `UNLINK` | Work. The module frees the storage in the background. | +| `FLUSHALL`, `FLUSHALL ASYNC` | Work. | + +## Topics + +* [Valkey Large Object - Getting Started](large-object-getting-started.md) - build the module, load it, and run your first commands. +* [Valkey Large Object - Use Cases and Examples](large-object-use-cases.md) - common patterns with worked examples. +* [Valkey Large Object - RDMA Transfers](large-object-rdma.md) - sessions, memory regions, checksums, and errors. +* [Valkey Large Object - Configuration and Monitoring](large-object-configuration.md) - configuration parameters, ACL, and `INFO` fields. diff --git a/topics/quickstart.md b/topics/quickstart.md index d8c733c0..1cc25385 100644 --- a/topics/quickstart.md +++ b/topics/quickstart.md @@ -110,6 +110,7 @@ Now that you have Valkey running and understand the basics, you can explore more * **[Valkey Bloom](bloomfilters.md)** * **[Valkey LDAP](ldap.md)** * **[Valkey Search](search.md)** + * **[Valkey Large Object](large-object.md)** (version 0.x) * **Publish/Subscribe Messaging:** Dive into Valkey’s Pub/Sub feature to build real-time apps (such as chat systems o live notifications). See the [**Pub/Sub** section](pubsub.md) of the docs for patterns and best practices (Valkey’s Pub/Sub supports pattern subscriptions and sharded channels for scalability). * **Clustering and High Availability:** When you need to scale out or ensure uptime, Valkey Cluster mode allows sharding data across multiple nodes with automatic failover. Check out the **[Valkey Cluster tutorial](cluster-tutorial.md)** for a step-by-step guide to setting up a cluster and using replication. * **Further Documentation:** Explore the **[Valkey Documentation by Topic](index.md)** for in-depth guides on persistence, security, Lua scripting, modules, and more. Key references include the [Commands Reference](../commands/) for details on every command, and the [FAQ](faq.md) for answers to common questions. diff --git a/wordlist b/wordlist index 79b857f9..d2d7a13a 100644 --- a/wordlist +++ b/wordlist @@ -135,6 +135,7 @@ CentOS Changelog changelogs charset +checksums Chemeris cheprasov ciphersuites @@ -170,6 +171,7 @@ Craigslist CRC CRC-16 CRC16 +CRC32C CRC64 CRDTs CRLF-terminated @@ -270,6 +272,7 @@ executables expiries explainer explainers +ext4 facto factorializing Failover @@ -387,6 +390,7 @@ incrby_get_mget indexable Infiniband ing +inode init int_vals internals-eventlib @@ -395,6 +399,7 @@ internals-sds internals-vm intsets invalidations +io_uring iojob IOPs iostat @@ -452,6 +457,7 @@ knockknock Kubernetes kqueue L3 +largeobj last-failover-wins lastkey lastVoteEpoch @@ -472,6 +478,7 @@ lenptr Levelgraph lexicographically libc +libfabric LibLZF libssl-dev libvalkey @@ -595,6 +602,7 @@ num-items numactl numkeys numreq +NVMe nx observability octothorpe @@ -645,6 +653,7 @@ pmessage Pool2 POP3 ppa:redislabs +pre-allocated pre-built pre-conditions pre-configured @@ -704,6 +713,7 @@ RDB-saving rdd rdd-1 rdd-2 +RDMA-capable reacquisition react-redlock readibility @@ -793,6 +803,7 @@ RU102 RU202 runid runlevels +rustup RW Rx/Tx S[1-9] @@ -883,6 +894,8 @@ subcommand. subcommand's Subcommands subcommands +subdirectories +subdirectory subevent subevents suboptimal @@ -913,6 +926,8 @@ TLS-encrypted tls-port tmp tmux +tokenizer +toolchain toolkits topologies tonumber