starling-0.1.0: A memcached client

MaintainerAntoine Latter <aslatter@gmail.com>

Network.Starling

Description

A haskell implementation of the memcahed protocol.

This implements the new binary protocol, so it only works with memcached version 1.3 and newer.

Example of usage, using the network package to obain a handle, and the OverloadedStrings language extension:

 h <- connectTo "filename" $ UnixSocket "filename"
 hSetBuffering h NoBuffering
 con <- open h
 set con "hello" "world"
 get con "hello"

In the above example we connect to a unix socket in the file "filename", set the key "hello" to the value "world" and then retrieve the value.

Operations are thread safe - multiple threads of execution may make concurrent requests on the memcahced connection.

Operations are blocking, but do not block other concurrent threads from placing requests on the connection.

Synopsis

Documentation

open :: Handle -> IO ConnectionSource

Create a connection. Please don't use the handle after opening a connection with it.

close :: Connection -> IO ()Source

Shut down the connection. Non-blocking.

data Connection Source

For thread safety of operations, we perform all requests on a wrapper around a handle.

type ResultM m a = m (Either (ResponseStatus, ByteString) a)Source

If an operation fails the result will return in Left with the failure code and a text description of the failure

set :: Connection -> Key -> Value -> Result ()Source

Set a value in the cache

get :: Connection -> Key -> Result ByteStringSource

Retrive a value from the cache

delete :: Connection -> Key -> Result ()Source

Delete an entry in the cache

add :: Connection -> Key -> Value -> Result ()Source

Set a vlue in the cache. Fails if a value is already defined for the indicated key.

replace :: Connection -> Key -> Value -> Result ()Source

Set a value in the cache. Fails if a value is not already defined for the indicated key.

update :: MonadIO m => Connection -> Key -> (Value -> m (Maybe Value)) -> ResultM m ()Source

Update a value in the cache. This operation requires two round trips. This operation can fail if the key is not present in the cache, or if the value changes in the cache between the two calls. So watch out! Even if the value exists the operation might not go through in the face of concurrent access.

Testing indicates that if we fail because we could not gaurantee atomicity the failure code will be KeyExists.

increment :: Connection -> Key -> Word64 -> Word64 -> Result Word64Source

Increment a value in the cache. The first Word64 argument is the amount by which to increment and the second is the intial value to use of the key does not yet have a value. The return value is the updated value in the cache.

decrement :: Connection -> Key -> Word64 -> Word64 -> Result Word64Source

Decrement a value in the cache. The first Word64 argument is the amount by which to decrement and the second is the intial value to use of the key does not yet have a value. The return value is the updated value in the cache.

flush :: Connection -> Result ()Source

Delete all entries in the cache

stats :: Connection -> Result [(ByteString, ByteString)]Source

Returns a list of stats about the server in key,value pairs

version :: Connection -> Result ByteStringSource

Returns the version of the server