memcached

Kind	ffi-c
Capabilities	ffi tcp
Categories	database caching ffi
Keywords	memcached cache database key-value

Memcached client for Kit using vendored mcmc C bindings

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and caches
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_memcached.c`	C FFI wrapper over the vendored memcached client
`c/kit_memcached.h`	C header for the FFI wrapper
`examples/basic.kit`	Minimal connection and get/set example
`examples/cas.kit`	Example: gets plus cas flow
`examples/live-smoke.kit`	Broader live smoke example covering the client surface
`examples/memcached.kit`	Canonical example with multi-key reads and stats
`kit.toml`	Package manifest with metadata and native build config
`src/memcached.kit`	kit-memcached client API for Kit
`tests/memcached.test.kit`	Live tests for the memcached client

Dependencies

No Kit package dependencies.

This package vendors the upstream mcmc C client in c/vendor/mcmc/, so no external memcached client library is required at build time.

Installation

kit add gitlab.com/kit-lang/packages/kit-memcached.git

Usage

import Kit.Memcached as Memcached

main = fn =>
  match Memcached.connect "127.0.0.1" 11211
    | Ok client ->
      defer Memcached.close client

      key-a = "greeting"
      key-b = "subject"
      Memcached.delete client key-a |> Result.unwrap
      Memcached.delete client key-b |> Result.unwrap
      Memcached.set client key-a "hello" |> Result.unwrap
      Memcached.set client key-b "world" |> Result.unwrap
      values = Memcached.get-many client [key-a, key-b] |> Result.unwrap

      println (show (Map.get values key-a))
      println (show (Map.get values key-b))
    | Err err ->
      println (show err)

main

Supported API areas:

TCP connection management with connect, close, is-connected?
Storage commands: set, set-ex, add, add-ex, replace, replace-ex, append, prepend
Retrieval commands: get, get-many, gets, gets-many
CAS commands: cas, cas-ex
Mutation and admin commands: delete, touch, flush-all, incr, decr
Server metadata: version, stats-text, stats, stats-settings-text, stats-settings, stats-slabs-text, stats-slabs, stats-items-text, stats-items

Development

Running Examples

Run the canonical example against a local memcached daemon:

KIT_MEMCACHED_HOST=127.0.0.1 KIT_MEMCACHED_PORT=11222 kit run --allow=ffi,tcp examples/memcached.kit

Run the CAS example:

KIT_MEMCACHED_HOST=127.0.0.1 KIT_MEMCACHED_PORT=11222 kit run --allow=ffi,tcp examples/cas.kit

Compile the live smoke example to a native binary:

kit build --allow=ffi,tcp examples/live-smoke.kit --no-spinner -o /tmp/kit_memcached_live_smoke
/tmp/kit_memcached_live_smoke

The examples use defer Memcached.close client after a successful connect, which is the intended cleanup pattern for the client handle returned by this package.

Running Tests

Run the live test suite:

kit test tests/memcached.test.kit

Running kit dev

Run the standard development workflow:

kit dev

This will:

Format and check source files in src/
Run tests in tests/

Local memcached daemon

Live examples and tests expect a memcached daemon to be available. A typical local command is:

memcached -p 11222 -U 0 -l 127.0.0.1

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/memcached/, making it available for import as Kit.Memcached in other projects.

License

This package is released under the MIT License - see LICENSE for details.

The vendored upstream mcmc client in c/vendor/mcmc/ is also released under the MIT License.

Exported Functions & Types

`MemcachedError`

Memcached client for Kit.

This package provides a focused client API for text-protocol memcached operations using a vendored C wrapper around the upstream mcmc client.

Variants

MemcachedConnectionError {message}

MemcachedCommandError {message}