Network.Starling

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.

Documentation

open :: Handle -> IO Connection

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

close :: Connection -> IO ()

Shut down the connection. Non-blocking.

data Connection

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

type Key = ByteString

type Value = ByteString

data StarlingError

An error consists of the error code returned by the server and a human-readble error string returned by the server.

Constructors

StarlingError ResponseStatus ByteString

Instances

Show StarlingError

Typeable StarlingError

Exception StarlingError

data ResponseStatus

Constructors

NoError

KeyNotFound

KeyExists

ValueTooLarge

InvalidArguments

ItemNotStored

IncrDecrOnNonNumeric

AuthRequired

FurtherAuthRequired

UnknownCommand

OutOfMemory

Instances

Eq ResponseStatus

Ord ResponseStatus

Read ResponseStatus

Show ResponseStatus

Typeable ResponseStatus

Exception ResponseStatus

Deserialize ResponseStatus

set :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> Value -> m ()

Set a value in the cache

get :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> m ByteString

Retrive a value from the cache

delete :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> m ()

Delete an entry in the cache

add :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> Value -> m ()

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

replace :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> Value -> m ()

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

update :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> (Value -> m (Maybe Value)) -> m ()

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 :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> Word64 -> Word64 -> m Word64

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 if the key does not yet have a value. The return value is the updated value in the cache.

decrement :: (MonadIO m, Failure StarlingError m) => Connection -> Key -> Word64 -> Word64 -> m Word64

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 if the key does not yet have a value. The return value is the updated value in the cache.

flush :: (MonadIO m, Failure StarlingError m) => Connection -> m ()

Delete all entries in the cache

stats :: (MonadIO m, Failure StarlingError m) => Connection -> m [(ByteString, ByteString)]

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

version :: (MonadIO m, Failure StarlingError m) => Connection -> m ByteString

Returns the version of the server

listAuthMechanisms :: (MonadIO m, Failure StarlingError m) => Connection -> m [AuthMechanism]

List allowed SASL mechanisms. The server must support SASL authentication.

auth :: (MonadIO m, Failure StarlingError m) => Connection -> AuthMechanism -> AuthData -> Maybe (AuthCallback m) -> m Bool

SASL authenitcation. Multi-step authentication is supported by un-folding the passed-in AuthCallback. Returns True if authentication is supported and complete. If the supplied callback completes while there are still steps remaining we throw FurtherAuthRequired.

type AuthMechanism = ByteString

type AuthData = ByteString

data AuthCallback m

Some authentications require mutliple back and forths between the client and the server. This type encapsulates that.

Constructors

AuthCallback (ByteString -> m (AuthData, Maybe (AuthCallback m)))