Maintainer | Antoine Latter <aslatter@gmail.com> |
---|
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.
- open :: Handle -> IO Connection
- close :: Connection -> IO ()
- data Connection
- type Key = ByteString
- type Value = ByteString
- data StarlingError = StarlingError ResponseStatus ByteString
- data ResponseStatus
- set :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Value -> m ()
- get :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> m ByteString
- delete :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> m ()
- add :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Value -> m ()
- replace :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Value -> m ()
- update :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> (Value -> m (Maybe Value)) -> m ()
- increment :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Word64 -> Word64 -> m Word64
- decrement :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Word64 -> Word64 -> m Word64
- flush :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m ()
- stats :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m [(ByteString, ByteString)]
- version :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m ByteString
- listAuthMechanisms :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m [AuthMechanism]
- auth :: (MonadIO m, MonadFailure StarlingError m) => Connection -> AuthMechanism -> AuthData -> Maybe (AuthCallback m) -> m Bool
- type AuthMechanism = ByteString
- type AuthData = ByteString
- data AuthCallback m = AuthCallback (ByteString -> m (AuthData, Maybe (AuthCallback m)))
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 Key = ByteStringSource
type Value = ByteStringSource
data StarlingError Source
An error consists of the error code returned by the server and a human-readble error string returned by the server.
data ResponseStatus Source
set :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Value -> m ()Source
Set a value in the cache
get :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> m ByteStringSource
Retrive a value from the cache
delete :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> m ()Source
Delete an entry in the cache
add :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Value -> m ()Source
Set a vlue in the cache. Fails if a value is already defined for the indicated key.
replace :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Value -> m ()Source
Set a value in the cache. Fails if a value is not already defined for the indicated key.
update :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> (Value -> m (Maybe Value)) -> 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 :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Word64 -> Word64 -> m 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 if the key does not yet have a value.
The return value is the updated value in the cache.
decrement :: (MonadIO m, MonadFailure StarlingError m) => Connection -> Key -> Word64 -> Word64 -> m 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 if the key does not yet have a value.
The return value is the updated value in the cache.
flush :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m ()Source
Delete all entries in the cache
stats :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m [(ByteString, ByteString)]Source
Returns a list of stats about the server in key,value pairs
version :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m ByteStringSource
Returns the version of the server
listAuthMechanisms :: (MonadIO m, MonadFailure StarlingError m) => Connection -> m [AuthMechanism]Source
List allowed SASL mechanisms. The server must support SASL authentication.
auth :: (MonadIO m, MonadFailure StarlingError m) => Connection -> AuthMechanism -> AuthData -> Maybe (AuthCallback m) -> m BoolSource
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 = ByteStringSource
type AuthData = ByteStringSource
data AuthCallback m Source
Some authentications require mutliple back and forths between the client and the server. This type encapsulates that.
AuthCallback (ByteString -> m (AuthData, Maybe (AuthCallback m))) |