object

# `memcached`

Portable Memcached client implementing the text (ASCII) protocol. Uses the sockets library for TCP communication.

Availability:
`logtalk_load(memcached(loader))`
Author: Paulo Moura
Version: 1:0:1
Date: 2026-06-14
Compilation flags:
`static, context_switching_calls`
Uses:
list
socket
user
Remarks:

> - Supported backends: ECLiPSe, GNU Prolog, SICStus Prolog, SWI-Prolog, and Trealla Prolog (same as the sockets library).

> - Protocol version: Implements the Memcached text (ASCII) protocol as documented in the official protocol.txt specification.

> - Connection: The default Memcached port is 11211. Connections are represented as opaque handles that should be passed to all other predicates.

> - Keys: Keys are atoms up to 250 characters. They must not include control characters or whitespace.

> - Flags: Flags are 32-bit unsigned integers stored alongside the data, opaque to the server.

> - Expiration: Expiration time in seconds. 0 means never expire. Values over 30 days (2592000) are treated as Unix timestamps.

> - Storage commands: Supports set, add, replace, append, prepend, and cas (check-and-set).

> - Retrieval commands: Supports get, gets (with CAS token), gat, and gats (get-and-touch).

> - Other commands: Supports delete, incr/decr, touch, flush_all, version, stats, and quit.

Inherited public predicates:
(none)

## Public predicates

### `connect/3`

Connects to a Memcached server at the given host and port. Returns a connection handle for subsequent operations.

Compilation flags:
`static`
Template:
`connect(Host,Port,Connection)`
Mode and number of proofs:
`connect(+atom,+integer,--compound)` - `one_or_error`
Exceptions:
Connection refused or network error:
`memcached_error(connection_failed)`

### `connect/2`

Connects to a Memcached server at the given host on the default port (11211). Returns a connection handle for subsequent operations.

Compilation flags:
`static`
Template:
`connect(Host,Connection)`
Mode and number of proofs:
`connect(+atom,--compound)` - `one_or_error`
Exceptions:
Connection refused or network error:
`memcached_error(connection_failed)`

### `disconnect/1`

Disconnects from the Memcached server. Sends a quit command before closing.

Compilation flags:
`static`
Template:
`disconnect(Connection)`
Mode and number of proofs:
`disconnect(+compound)` - `one`

### `set/5`

Stores the data unconditionally. Overwrites any existing data for the key.

Compilation flags:
`static`
Template:
`set(Connection,Key,Value,Flags,ExpTime)`
Mode and number of proofs:
`set(+compound,+atom,+atom,+integer,+integer)` - `one_or_error`
Exceptions:
Storage failed:
`memcached_error(not_stored)`
Network error:
`memcached_error(Error)`

### `set/3`

Stores the data unconditionally with default flags (0) and no expiration (0).

Compilation flags:
`static`
Template:
`set(Connection,Key,Value)`
Mode and number of proofs:
`set(+compound,+atom,+atom)` - `one_or_error`
Exceptions:
Storage failed:
`memcached_error(not_stored)`
Network error:
`memcached_error(Error)`

### `add/5`

Stores the data only if the key does not already exist.

Compilation flags:
`static`
Template:
`add(Connection,Key,Value,Flags,ExpTime)`
Mode and number of proofs:
`add(+compound,+atom,+atom,+integer,+integer)` - `one_or_error`
Exceptions:
Key already exists:
`memcached_error(not_stored)`
Network error:
`memcached_error(Error)`

### `replace/5`

Stores the data only if the key already exists.

Compilation flags:
`static`
Template:
`replace(Connection,Key,Value,Flags,ExpTime)`
Mode and number of proofs:
`replace(+compound,+atom,+atom,+integer,+integer)` - `one_or_error`
Exceptions:
Key does not exist:
`memcached_error(not_stored)`
Network error:
`memcached_error(Error)`

### `append/3`

Appends the data to the end of an existing item’s data.

Compilation flags:
`static`
Template:
`append(Connection,Key,Value)`
Mode and number of proofs:
`append(+compound,+atom,+atom)` - `one_or_error`
Exceptions:
Key does not exist:
`memcached_error(not_stored)`
Network error:
`memcached_error(Error)`

### `prepend/3`

Prepends the data to the beginning of an existing item’s data.

Compilation flags:
`static`
Template:
`prepend(Connection,Key,Value)`
Mode and number of proofs:
`prepend(+compound,+atom,+atom)` - `one_or_error`
Exceptions:
Key does not exist:
`memcached_error(not_stored)`
Network error:
`memcached_error(Error)`

### `cas/6`

Stores the data only if no one else has updated it since the given CAS unique value was obtained (via gets/3).

Compilation flags:
`static`
Template:
`cas(Connection,Key,Value,Flags,ExpTime,CasUnique)`
Mode and number of proofs:
`cas(+compound,+atom,+atom,+integer,+integer,+integer)` - `one_or_error`
Exceptions:
CAS value mismatch (item modified by another client):
`memcached_error(exists)`
Key does not exist:
`memcached_error(not_found)`
Network error:
`memcached_error(Error)`

### `get/3`

Retrieves the value associated with the key. Fails if the key is not found.

Compilation flags:
`static`
Template:
`get(Connection,Key,Value)`
Mode and number of proofs:
`get(+compound,+atom,-atom)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `get` command:
`memcached_error(Error)`

### `get/4`

Retrieves the value and flags associated with the key. Fails if the key is not found.

Compilation flags:
`static`
Template:
`get(Connection,Key,Value,Flags)`
Mode and number of proofs:
`get(+compound,+atom,-atom,-integer)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `get` command:
`memcached_error(Error)`

### `gets/4`

Retrieves the value and CAS unique token for the key. Fails if the key is not found. The CAS value is used with the cas/6 predicate.

Compilation flags:
`static`
Template:
`gets(Connection,Key,Value,CasUnique)`
Mode and number of proofs:
`gets(+compound,+atom,-atom,-integer)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `gets` command:
`memcached_error(Error)`

### `gets/5`

Retrieves the value, flags, and CAS unique token for the key. Fails if the key is not found.

Compilation flags:
`static`
Template:
`gets(Connection,Key,Value,Flags,CasUnique)`
Mode and number of proofs:
`gets(+compound,+atom,-atom,-integer,-integer)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `gets` command:
`memcached_error(Error)`

### `mget/3`

Retrieves multiple keys at once. Returns a list of `item(Key, Value, Flags)` terms for found keys.

Compilation flags:
`static`
Template:
`mget(Connection,Keys,Items)`
Mode and number of proofs:
`mget(+compound,+list(atom),-list(compound))` - `one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the multi-key retrieval command:
`memcached_error(Error)`

### `delete/2`

Deletes the item with the given key. Fails if the key is not found.

Compilation flags:
`static`
Template:
`delete(Connection,Key)`
Mode and number of proofs:
`delete(+compound,+atom)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `delete` command:
`memcached_error(Error)`

### `incr/4`

Increments the numeric value of the given key by the specified amount. Returns the new value. The item must already exist and contain a decimal representation of a 64-bit unsigned integer. Fails if the key is not found.

Compilation flags:
`static`
Template:
`incr(Connection,Key,Amount,NewValue)`
Mode and number of proofs:
`incr(+compound,+atom,+integer,-integer)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `incr` command:
`memcached_error(Error)`

### `decr/4`

Decrements the numeric value of the given key by the specified amount. Returns the new value. Underflow is caught: decrementing below 0 yields 0. Fails if the key is not found.

Compilation flags:
`static`
Template:
`decr(Connection,Key,Amount,NewValue)`
Mode and number of proofs:
`decr(+compound,+atom,+integer,-integer)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `decr` command:
`memcached_error(Error)`

### `touch/3`

Updates the expiration time of the given key without fetching the data. Fails if the key is not found.

Compilation flags:
`static`
Template:
`touch(Connection,Key,ExpTime)`
Mode and number of proofs:
`touch(+compound,+atom,+integer)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `touch` command:
`memcached_error(Error)`

### `gat/4`

Gets the value of the key and updates its expiration time. Fails if the key is not found.

Compilation flags:
`static`
Template:
`gat(Connection,Key,ExpTime,Value)`
Mode and number of proofs:
`gat(+compound,+atom,+integer,-atom)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `gat` command:
`memcached_error(Error)`

### `gats/5`

Gets the value and CAS unique token of the key and updates its expiration time. Fails if the key is not found.

Compilation flags:
`static`
Template:
`gats(Connection,Key,ExpTime,Value,CasUnique)`
Mode and number of proofs:
`gats(+compound,+atom,+integer,-atom,-integer)` - `zero_or_one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `gats` command:
`memcached_error(Error)`

### `flush_all/1`

Invalidates all existing items immediately.

Compilation flags:
`static`
Template:
`flush_all(Connection)`
Mode and number of proofs:
`flush_all(+compound)` - `one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `flush_all` command:
`memcached_error(Error)`
The server replies with an error to the `flush_all` command:
`memcached_error(server_error(Message))`

### `flush_all/2`

Invalidates all existing items after the specified number of seconds.

Compilation flags:
`static`
Template:
`flush_all(Connection,Delay)`
Mode and number of proofs:
`flush_all(+compound,+integer)` - `one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the delayed `flush_all` command:
`memcached_error(Error)`
The server replies with an error to the delayed `flush_all` command:
`memcached_error(server_error(Message))`

### `version/2`

Returns the version string of the Memcached server.

Compilation flags:
`static`
Template:
`version(Connection,Version)`
Mode and number of proofs:
`version(+compound,-atom)` - `one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `version` command:
`memcached_error(Error)`
The server replies with an unexpected or error response to the `version` command:
`memcached_error(server_error(Message))`

### `stats/2`

Returns general-purpose statistics as a list of `stat(Name, Value)` terms.

Compilation flags:
`static`
Template:
`stats(Connection,Stats)`
Mode and number of proofs:
`stats(+compound,-list(compound))` - `one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the `stats` command:
`memcached_error(Error)`

### `stats/3`

Returns statistics for the given argument (e.g. `items`, `slabs`, `sizes`) as a list of `stat(Name, Value)` terms.

Compilation flags:
`static`
Template:
`stats(Connection,Argument,Stats)`
Mode and number of proofs:
`stats(+compound,+atom,-list(compound))` - `one_or_error`
Exceptions:
Network or stream I/O error while sending or reading the parameterized `stats` command:
`memcached_error(Error)`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)