TABLE OF CONTENTS valkey.library/--background-- valkey.library/Append valkey.library/DBSize valkey.library/Del valkey.library/Exists valkey.library/Expire valkey.library/ExpireAt valkey.library/FlushDB valkey.library/Get valkey.library/GetAllKeys valkey.library/GetExtMemStats valkey.library/GetRange valkey.library/GetStats valkey.library/IncrBy valkey.library/Persist valkey.library/PurgeExpired valkey.library/ReadVal valkey.library/Set valkey.library/SetNX valkey.library/StrLen valkey.library/TTL valkey.library/--background-- valkey.library/--background-- DESCRIPTION valkey.library is a high-performance, in-memory key-value database shared library natively built for AmigaOS 4.1 on PowerPC (AmigaOne X5000). It implements a Dual-Tier memory architecture: 1. 32-Bit Exec System Heap (<2GB boundary): Fast MurmurHash3 index, key metadata, and Short-String Inline Optimization (<= 48 bytes). 2. ExecSG Extended Memory (ASOT_EXTMEM / 36-bit Physical DDR3 RAM): Gigabytes of upper physical DDR3 memory allocated via libextmem for large string payloads and blobs without consuming scarce 32-bit Exec heap space. Thread Safety: All library methods are fully thread-safe and re-entrant across tasks, protected by reader-writer SignalSemaphores. OPENING THE LIBRARY #include #include struct Library *ValKeyBase = IExec->OpenLibrary("valkey.library", 1); struct ValKeyIFace *IValKey = (struct ValKeyIFace *)IExec->GetInterface( ValKeyBase, "main", 1, NULL); if (IValKey) { IValKey->Set("user:1", 6, "AmigaOS", 7, 0); IExec->DropInterface((struct Interface *)IValKey); } if (ValKeyBase) { IExec->CloseLibrary(ValKeyBase); } valkey.library/Set valkey.library/Set NAME Set -- Store a key-value pair in the database. SYNOPSIS bool Set(struct ValKeyIFace *Self, const char *key, uint32 key_len, const void *val, uint32 val_len, uint32 ttl_secs); FUNCTION Stores the specified value associated with the given key string. If val_len <= 48 bytes, the value is stored inline directly in the 32-bit heap node with zero ExtMem allocation overhead. If val_len > 48 bytes, the payload is allocated and stored directly in physical ExtMem DDR3 RAM. INPUTS Self - Pointer to ValKeyIFace interface. key - Null-terminated or binary key string pointer. key_len - Length of the key in bytes. val - Pointer to the value data. val_len - Length of the value data in bytes. ttl_secs - Time-To-Live in seconds (0 = persistent / no expiration). RESULT true if successfully stored, false on memory allocation failure. SEE ALSO Get, SetNX, Del, Expire valkey.library/SetNX valkey.library/SetNX NAME SetNX -- Store a key-value pair only if the key does not already exist. SYNOPSIS bool SetNX(struct ValKeyIFace *Self, const char *key, uint32 key_len, const void *val, uint32 val_len, uint32 ttl_secs); FUNCTION Atomically checks if the key exists. If it does not exist, stores the key-value pair. If it already exists, no modification is performed. INPUTS Self - Pointer to ValKeyIFace interface. key - Pointer to key string. key_len - Length of key in bytes. val - Pointer to value data. val_len - Length of value data in bytes. ttl_secs - Expiration in seconds (0 = no expiry). RESULT true if key was set (did not exist before), false if key already existed. valkey.library/Get valkey.library/Get NAME Get -- Retrieve the value associated with a key. SYNOPSIS bool Get(struct ValKeyIFace *Self, const char *key, uint32 key_len, void **out_val, uint32 *out_val_len, bool *out_need_free); FUNCTION Looks up the active key and returns a pointer to its value data. If the value is stored inline, out_val points directly into the internal buffer and out_need_free is set to false. If the value is stored in ExtMem, a temporary copy is allocated in 32-bit heap, and out_need_free is set to true (the caller must call free(*out_val)). INPUTS Self - Pointer to ValKeyIFace interface. key - Key string pointer. key_len - Length of key in bytes. out_val - Pointer to void* where value address is written. out_val_len - Pointer to uint32 where value length is written. out_need_free- Pointer to bool set to true if caller must free(*out_val). RESULT true if key was found and active, false if key does not exist or expired. SEE ALSO ReadVal, Set, Del valkey.library/ReadVal valkey.library/ReadVal NAME ReadVal -- Zero-copy streaming read from a key's value at an offset. SYNOPSIS int32 ReadVal(struct ValKeyIFace *Self, const char *key, uint32 key_len, void *dest_buf, uint32 dest_size, uint32 offset); FUNCTION Reads up to dest_size bytes starting at byte offset directly into the caller-provided buffer without allocating heap memory. Ideal for streaming multi-megabyte blobs from physical ExtMem DDR3 RAM. INPUTS Self - Pointer to ValKeyIFace interface. key - Key string pointer. key_len - Length of key in bytes. dest_buf - Destination buffer pointer. dest_size - Maximum bytes to read into dest_buf. offset - Byte offset within the value payload. RESULT Number of bytes actually read (>= 0), or -1 if key does not exist. valkey.library/Del valkey.library/Del NAME Del -- Delete a key and free its associated ExtMem resources. SYNOPSIS bool Del(struct ValKeyIFace *Self, const char *key, uint32 key_len); FUNCTION Removes the specified key from the database and frees any associated physical ExtMem allocation. INPUTS Self - Pointer to ValKeyIFace interface. key - Key string pointer. key_len - Length of key in bytes. RESULT true if key was found and deleted, false if key did not exist. valkey.library/Exists valkey.library/Exists NAME Exists -- Check if a key exists and is not expired. SYNOPSIS bool Exists(struct ValKeyIFace *Self, const char *key, uint32 key_len); RESULT true if key exists and is active, false otherwise. valkey.library/IncrBy valkey.library/IncrBy NAME IncrBy -- Increment the integer value of a key by a specified amount. SYNOPSIS bool IncrBy(struct ValKeyIFace *Self, const char *key, uint32 key_len, int64 increment, int64 *out_new_val); FUNCTION Parses the key's value as a 64-bit integer, adds the specified increment, and stores the result back. If the key does not exist, it is initialized to 0 before applying the increment. INPUTS Self - Pointer to ValKeyIFace interface. key - Key string pointer. key_len - Length of key in bytes. increment - Integer amount to add (can be negative for decrement). out_new_val - Pointer to int64 where resulting value is stored. RESULT true on success, false if existing value is not a valid integer. valkey.library/Append valkey.library/Append NAME Append -- Append binary or string data to an existing key's value. SYNOPSIS bool Append(struct ValKeyIFace *Self, const char *key, uint32 key_len, const void *data, uint32 data_len, uint32 *out_new_len); FUNCTION Appends data to the key. If the key did not exist, it is created. If the new length exceeds 48 bytes, it is automatically promoted from inline 32-bit heap to physical ExtMem DDR3 RAM. RESULT true on success, false on allocation failure. valkey.library/GetRange valkey.library/GetRange NAME GetRange -- Retrieve a substring slice of a key's value. SYNOPSIS bool GetRange(struct ValKeyIFace *Self, const char *key, uint32 key_len, int32 start, int32 end, void **out_buf, uint32 *out_len); FUNCTION Returns a substring determined by the start and end offsets (0-indexed). Negative offsets represent offsets from the end (-1 is the last byte). The caller must free(*out_buf) when finished. RESULT true on success, false if key does not exist. valkey.library/Expire valkey.library/Expire NAME Expire -- Set a key's time-to-live in seconds. SYNOPSIS bool Expire(struct ValKeyIFace *Self, const char *key, uint32 key_len, uint32 ttl_secs); RESULT true if TTL was updated, false if key does not exist. valkey.library/TTL valkey.library/TTL NAME TTL -- Get the remaining time-to-live of a key in seconds. SYNOPSIS int64 TTL(struct ValKeyIFace *Self, const char *key, uint32 key_len); RESULT Remaining TTL in seconds (>= 0), -1 if key has no TTL, -2 if key does not exist. valkey.library/Persist valkey.library/Persist NAME Persist -- Remove the expiration timeout from a key. SYNOPSIS bool Persist(struct ValKeyIFace *Self, const char *key, uint32 key_len); RESULT true if timeout was removed, false if key had no expiry or does not exist. valkey.library/DBSize valkey.library/DBSize NAME DBSize -- Return the total number of keys in the database. SYNOPSIS uint32 DBSize(struct ValKeyIFace *Self); RESULT Total number of active keys. valkey.library/FlushDB valkey.library/FlushDB NAME FlushDB -- Delete all keys and reset memory pools. SYNOPSIS void FlushDB(struct ValKeyIFace *Self); valkey.library/GetStats valkey.library/GetStats NAME GetStats -- Retrieve keyspace and performance statistics. SYNOPSIS void GetStats(struct ValKeyIFace *Self, KVStats *stats); INPUTS stats - Pointer to KVStats structure to receive statistics. valkey.library/GetExtMemStats valkey.library/GetExtMemStats NAME GetExtMemStats -- Retrieve physical ExecSG ExtMem hardware statistics. SYNOPSIS void GetExtMemStats(struct ValKeyIFace *Self, ExtMemStats *stats); INPUTS stats - Pointer to ExtMemStats structure to receive statistics. valkey.library/GetAllKeys valkey.library/GetAllKeys NAME GetAllKeys -- Iterate over all active keys with a callback function. SYNOPSIS void GetAllKeys(struct ValKeyIFace *Self, KVKeyCallback cb, void *user_data); INPUTS cb - Callback function `bool (*cb)(const char *key, uint32 len, void *data)`. Return true to continue iteration, false to stop early. user_data - Caller-provided context passed to callback.