#memcache API reference

A client for a memcached server, speaking its classic text protocol over the net system library. Store with an expiration (set / add), read (get), remove (delete), count atomically (incr / decr), and re-arm a key's expiry (touch). memcached is a volatile cache - keys expire on their exptime and the server evicts under memory pressure - so it suits sessions, rate limits, and derived data, not a system of record. exptime is seconds (0 = never expire, until evicted). A protocol error (ERROR / CLIENT_ERROR / SERVER_ERROR) throws a catchable Error (kind "memcache"). The value block is framed over bytes by the server's byte count, so a value whose byte length differs from its rune length (any non-ASCII UTF-8 text) round-trips byte-exact. Needs the default jennifer binary (uses net).

Import with import "memcache.j" as memcache;. See the memcache guide for prose and examples.

#Functions

#memcache.add(session as Session, key as string, value as string, exptime as int)

Store value at key only if the key is absent. The atomic build block for locks and "create if new".

Parameters

• session {Session} - the open session
• key {string} - the key to write
• value {string} - the value to store
• exptime {int} - the TTL in seconds (0 = never expire, until evicted)

Returns {bool} - whether it was stored (false when the key already exists)

Throws

• {Error} - kind "memcache" on an unexpected reply

#memcache.cas(session as Session, key as string, value as string, exptime as int, casId as int)

Check-and-set: store value at key only if its CAS token still matches casId (from a prior gets) - i.e. only if no one else changed it meanwhile. The optimistic-concurrency primitive: gets, compute a new value, cas, and retry on "exists". Returns "stored" (success), "exists" (someone else changed it - retry), or "not_found" (the key is gone / expired).

Parameters

• session {Session} - the open session
• key {string} - the key to write
• value {string} - the new value
• exptime {int} - the TTL in seconds (0 = never expire, until evicted)
• casId {int} - the CAS token from a prior gets

Returns {string} - "stored", "exists", or "not_found"

Throws

• {Error} - kind "memcache" on an unexpected reply

#memcache.connect(opts as Options)

Open a session to the memcached server.

Parameters

• opts {Options} - the connection settings

Returns {Session} - the open session

#memcache.decr(session as Session, key as string, delta as int)

Atomically subtract delta from the counter at key (not below 0).

Parameters

• session {Session} - the open session
• key {string} - the counter key
• delta {int} - the amount to subtract

Returns {int} - the new value, or -1 when the key is absent

#memcache.delete(session as Session, key as string)

Remove key.

Parameters

• session {Session} - the open session
• key {string} - the key to remove

Returns {bool} - whether the key existed

Throws

• {Error} - kind "memcache" on an unexpected reply

#memcache.get(session as Session, key as string)

Return the string value of key, or "" when the key is absent / expired.

Parameters

• session {Session} - the open session
• key {string} - the key to read

Returns {string} - the value, or "" when absent / expired

#memcache.getBytes(session as Session, key as string)

Return the raw bytes value of key, or empty bytes when absent / expired (the binary counterpart to get). It never UTF-8-decodes, so a value stored with setBytes round-trips exactly.

Parameters

• session {Session} - the open session
• key {string} - the key to read

Returns {bytes} - the value, or empty bytes when absent / expired

#memcache.getMulti(session as Session, keys as list of string)

Fetch several keys in one round-trip (multi-key get) as a map of string to string; a missing / expired key is simply absent from the map, so maps.has distinguishes it. Cheaper than N separate gets.

Parameters

• session {Session} - the open session
• keys {list of string} - the keys to read

Returns {map of string to string} - the found key -> value pairs

#memcache.gets(session as Session, key as string)

Read key with its CAS token (gets), for a check-and-set update. The returned Item carries the value, the cas token, and whether the key was found; pass its cas to cas so the store only succeeds if no one else changed the value meanwhile.

Parameters

• session {Session} - the open session
• key {string} - the key to read

Returns {Item} - the value, CAS token, and found flag

#memcache.incr(session as Session, key as string, delta as int)

Atomically add delta to the counter at key.

Parameters

• session {Session} - the open session
• key {string} - the counter key
• delta {int} - the amount to add

Returns {int} - the new value, or -1 when the key is absent

#memcache.quit(session as Session)

End the session and close the connection.

Parameters

• session {Session} - the open session

#memcache.set(session as Session, key as string, value as string, exptime as int)

Store value at key with an exptime-second TTL, replacing any existing value.

Parameters

• session {Session} - the open session
• key {string} - the key to write
• value {string} - the value to store
• exptime {int} - the TTL in seconds (0 = never expire, until evicted)

Throws

• {Error} - kind "memcache" on a non-STORED reply

#memcache.setBytes(session as Session, key as string, value as bytes, exptime as int)

Store a raw bytes value at key, byte-for-byte (the binary counterpart to set). A serialized blob, a compressed payload, or an image round-trips exactly; read it back with getBytes, not get (the string reader throws on a non-UTF-8 value).

Parameters

• session {Session} - the open session
• key {string} - the key to write
• value {bytes} - the raw value to store
• exptime {int} - the TTL in seconds (0 = never expire, until evicted)

Throws

• {Error} - kind "memcache" on a non-STORED reply

#memcache.touch(session as Session, key as string, exptime as int)

Re-arm key's expiry to exptime seconds.

Parameters

• session {Session} - the open session
• key {string} - the key to re-arm
• exptime {int} - the new TTL in seconds (0 = never expire, until evicted)

Returns {bool} - whether the key existed

Throws

• {Error} - kind "memcache" on an unexpected reply

#Structs

#memcache.Item

One value read by gets: its string value, the server's CAS token (an opaque version counter), and whether the key was found. Pass cas to cas for a check-and-set that only stores if no one else changed the value meanwhile.

#memcache.Options

Connection settings (plaintext; memcached's text protocol has no auth / TLS).

#memcache.Session

An open memcached connection.