-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A memcached client library.
--   
--   A client library for a memcached cluster.
--   
--   It supports the binary memcached protocol and SASL authentication. No
--   support for the ASCII protocol is provided. It supports connecting to
--   a single, or a cluster of memcached servers. When connecting to a
--   cluser, consistent hashing is used for routing requests to the
--   appropriate server.
--   
--   Complete coverage of the memcached protocol is provided except for
--   multi-get and other pipelined operations.
--   
--   Basic usage is:
--   
--   <pre>
--   import qualified Database.Memcache.Client as M
--   
--   mc &lt;- M.newClient [M.ServerSpec "localhost" 11211 M.NoAuth] M.defaultOptions
--   M.set mc "key" "value" 0 0
--   v &lt;- M.get mc "key"
--   </pre>
--   
--   You should only need to import <a>Database.Memcache.Client</a>, but
--   for now other modules are exposed.
@package memcache
@version 0.1.0.1


-- | Stores the various types needed by memcache. Mostly concerned with the
--   representation of the protocol.
module Database.Memcache.Types

-- | SASL Authentication information for a server.
data Authentication
Auth :: !Username -> !Password -> Authentication
[username] :: Authentication -> !Username
[password] :: Authentication -> !Password
NoAuth :: Authentication

-- | Username for authentication.
type Username = ByteString

-- | Password for authentication.
type Password = ByteString
data Q
Loud :: Q
Quiet :: Q
data K
NoKey :: K
IncludeKey :: K
type Key = ByteString
type Value = ByteString
type Extras = ByteString
type Initial = Word64
type Delta = Word64
type Expiration = Word32
type Flags = Word32
type Version = Word64
mEMCACHE_HEADER_SIZE :: Int
data Header
Header :: Word8 -> Word16 -> Word8 -> Status -> Word32 -> Word32 -> Version -> Header
[op] :: Header -> Word8
[keyLen] :: Header -> Word16
[extraLen] :: Header -> Word8
[status] :: Header -> Status
[bodyLen] :: Header -> Word32
[opaque] :: Header -> Word32
[cas] :: Header -> Version
data Request
Req :: OpRequest -> Word32 -> Version -> Request
[reqOp] :: Request -> OpRequest
[reqOpaque] :: Request -> Word32
[reqCas] :: Request -> Version
data OpRequest
ReqGet :: Q -> K -> Key -> OpRequest
ReqSet :: Q -> Key -> Value -> SESet -> OpRequest
ReqAdd :: Q -> Key -> Value -> SESet -> OpRequest
ReqReplace :: Q -> Key -> Value -> SESet -> OpRequest
ReqDelete :: Q -> Key -> OpRequest
ReqIncrement :: Q -> Key -> SEIncr -> OpRequest
ReqDecrement :: Q -> Key -> SEIncr -> OpRequest
ReqAppend :: Q -> Key -> Value -> OpRequest
ReqPrepend :: Q -> Key -> Value -> OpRequest
ReqTouch :: Key -> SETouch -> OpRequest
ReqGAT :: Q -> K -> Key -> SETouch -> OpRequest
ReqFlush :: Q -> (Maybe SETouch) -> OpRequest
ReqNoop :: OpRequest
ReqVersion :: OpRequest
ReqStat :: (Maybe Key) -> OpRequest
ReqQuit :: Q -> OpRequest
ReqSASLList :: OpRequest
ReqSASLStart :: Key -> Value -> OpRequest
ReqSASLStep :: Key -> Value -> OpRequest
data SESet
SESet :: Flags -> Expiration -> SESet
data SEIncr
SEIncr :: Initial -> Delta -> Expiration -> SEIncr
data SETouch
SETouch :: Expiration -> SETouch
emptyReq :: Request
data Response
Res :: OpResponse -> Status -> Word32 -> Version -> Response
[resOp] :: Response -> OpResponse
[resStatus] :: Response -> Status
[resOpaque] :: Response -> Word32
[resCas] :: Response -> Version
data OpResponse
ResGet :: Q -> Value -> Flags -> OpResponse
ResGetK :: Q -> Key -> Value -> Flags -> OpResponse
ResSet :: Q -> OpResponse
ResAdd :: Q -> OpResponse
ResReplace :: Q -> OpResponse
ResDelete :: Q -> OpResponse
ResIncrement :: Q -> Word64 -> OpResponse
ResDecrement :: Q -> Word64 -> OpResponse
ResAppend :: Q -> OpResponse
ResPrepend :: Q -> OpResponse
ResTouch :: OpResponse
ResGAT :: Q -> Value -> Flags -> OpResponse
ResGATK :: Q -> Key -> Value -> Flags -> OpResponse
ResFlush :: Q -> OpResponse
ResNoop :: OpResponse
ResVersion :: Value -> OpResponse
ResStat :: Key -> Value -> OpResponse
ResQuit :: Q -> OpResponse
ResSASLList :: Value -> OpResponse
ResSASLStart :: OpResponse
ResSASLStep :: OpResponse
data Status
NoError :: Status
ErrKeyNotFound :: Status
ErrKeyExists :: Status
ErrValueTooLarge :: Status
ErrInvalidArgs :: Status
ErrItemNotStored :: Status
ErrValueNonNumeric :: Status
ErrUnknownCommand :: Status
ErrOutOfMemory :: Status
SaslAuthFail :: Status
SaslAuthContinue :: Status
data ProtocolError
ProtocolError :: String -> Maybe Header -> [String] -> ProtocolError
[protocolMessage] :: ProtocolError -> String
[protocolHeader] :: ProtocolError -> Maybe Header
[protocolParams] :: ProtocolError -> [String]
data IncorrectResponse
IncorrectResponse :: String -> Response -> IncorrectResponse
[increspMessage] :: IncorrectResponse -> String
[increspActual] :: IncorrectResponse -> Response
instance GHC.Show.Show Database.Memcache.Types.IncorrectResponse
instance GHC.Classes.Eq Database.Memcache.Types.IncorrectResponse
instance GHC.Show.Show Database.Memcache.Types.ProtocolError
instance GHC.Classes.Eq Database.Memcache.Types.ProtocolError
instance GHC.Show.Show Database.Memcache.Types.Header
instance GHC.Classes.Eq Database.Memcache.Types.Header
instance GHC.Show.Show Database.Memcache.Types.Response
instance GHC.Classes.Eq Database.Memcache.Types.Response
instance GHC.Show.Show Database.Memcache.Types.Status
instance GHC.Classes.Eq Database.Memcache.Types.Status
instance GHC.Show.Show Database.Memcache.Types.OpResponse
instance GHC.Classes.Eq Database.Memcache.Types.OpResponse
instance GHC.Show.Show Database.Memcache.Types.Request
instance GHC.Classes.Eq Database.Memcache.Types.Request
instance GHC.Show.Show Database.Memcache.Types.OpRequest
instance GHC.Classes.Eq Database.Memcache.Types.OpRequest
instance GHC.Show.Show Database.Memcache.Types.SETouch
instance GHC.Classes.Eq Database.Memcache.Types.SETouch
instance GHC.Show.Show Database.Memcache.Types.SEIncr
instance GHC.Classes.Eq Database.Memcache.Types.SEIncr
instance GHC.Show.Show Database.Memcache.Types.SESet
instance GHC.Classes.Eq Database.Memcache.Types.SESet
instance GHC.Show.Show Database.Memcache.Types.K
instance GHC.Classes.Eq Database.Memcache.Types.K
instance GHC.Show.Show Database.Memcache.Types.Q
instance GHC.Classes.Eq Database.Memcache.Types.Q
instance GHC.Classes.Eq Database.Memcache.Types.Authentication
instance GHC.Show.Show Database.Memcache.Types.Authentication
instance GHC.Exception.Exception Database.Memcache.Types.ProtocolError
instance GHC.Exception.Exception Database.Memcache.Types.IncorrectResponse


-- | Memcached related errors and exception handling.
module Database.Memcache.Errors

-- | Exceptions that may be thrown by Memcache. These are expected error
--   codes returned by a memcached server.
data MemcacheError
MemErrNoKey :: MemcacheError
MemErrKeyExists :: MemcacheError
MemErrValueTooLarge :: MemcacheError
MemErrInvalidArgs :: MemcacheError
MemErrStoreFailed :: MemcacheError
MemErrValueNonNumeric :: MemcacheError
MemErrUnknownCmd :: MemcacheError
MemErrOutOfMemory :: MemcacheError
MemErrAuthFail :: MemcacheError

-- | Convert a status to an error. Note, not all status's are errors and so
--   this is a partial function!
statusToError :: Status -> MemcacheError

-- | Convert a status to an exception. Note, not all status's are errors
--   and so this is not a complete function!
throwStatus :: Status -> IO a

-- | Throw an IncorrectResponse exception for a wrong received response.
throwIncorrectRes :: Response -> String -> IO a

-- | Errors that occur between the client and server in communicating.
--   These are unexpected exceptions, such as network failures or garbage
--   data.
data ClientError
NotEnoughBytes :: ClientError
instance GHC.Show.Show Database.Memcache.Errors.ClientError
instance GHC.Classes.Eq Database.Memcache.Errors.ClientError
instance GHC.Show.Show Database.Memcache.Errors.MemcacheError
instance GHC.Classes.Eq Database.Memcache.Errors.MemcacheError
instance GHC.Exception.Exception Database.Memcache.Errors.MemcacheError
instance GHC.Exception.Exception Database.Memcache.Errors.ClientError


-- | Deals with serializing and parsing memcached requests and responses.
module Database.Memcache.Wire

-- | Send a request to the memcached server.
send :: Socket -> Request -> IO ()

-- | Retrieve a single response from the memcached server. TODO: read into
--   buffer to minimize read syscalls
recv :: Socket -> IO Response

-- | Serialize a request to a ByteString Builder.
szRequest :: Request -> Builder

-- | Serialize a request to a ByteString.
szRequest' :: Request -> ByteString

-- | Deserialize a Response.
dzResponse :: Get Response

-- | Deserialize a Response from a ByteString.
dzResponse' :: ByteString -> Response

-- | Deserialize a Header.
dzHeader :: Get Header

-- | Deserialize a Header from a ByteString.
dzHeader' :: ByteString -> Header

-- | Deserialize a Response body.
dzBody :: Header -> Get Response

-- | Deserialize a Response body from a ByteString.
dzBody' :: Header -> ByteString -> Response


-- | SASL authentication support for memcache.
module Database.Memcache.SASL

-- | Perform SASL authentication with the server.
authenticate :: Socket -> Authentication -> IO ()

-- | SASL Authentication information for a server.
data Authentication
Auth :: !Username -> !Password -> Authentication
[username] :: Authentication -> !Username
[password] :: Authentication -> !Password
NoAuth :: Authentication

-- | Username for authentication.
type Username = ByteString

-- | Password for authentication.
type Password = ByteString


-- | Handles the connections between a memcached client and a single
--   server.
module Database.Memcache.Server

-- | A memcached server connection.
data Server

-- | Create a new memcached connection.
newServer :: HostName -> PortNumber -> Authentication -> IO Server

-- | Send and receive a single request/response pair to the memcached
--   server.
sendRecv :: Server -> Request -> IO Response

-- | Run a function with access to an server socket for using <a>send</a>
--   and <a>recv</a>.
withSocket :: Server -> (Socket -> IO a) -> IO a

-- | Close the server connection. If you perform another operation after
--   this, the connection will be re-established.
close :: Server -> IO ()
instance GHC.Show.Show Database.Memcache.Server.Server
instance GHC.Classes.Eq Database.Memcache.Server.Server
instance GHC.Classes.Ord Database.Memcache.Server.Server


-- | A raw, low level interface to the memcached protocol.
--   
--   The various operations are represented in full as they appear at the
--   protocol level and so aren't generally well suited for application
--   use. Instead, applications should use Database.Memcache.Client which
--   presents a higher level API suited for application use.
module Database.Memcache.Protocol
get :: Server -> Key -> IO (Maybe (Value, Flags, Version))
gat :: Server -> Key -> Expiration -> IO (Maybe (Value, Flags, Version))
touch :: Server -> Key -> Expiration -> IO (Maybe Version)
set :: Server -> Key -> Value -> Flags -> Expiration -> IO Version
set' :: Server -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe Version)
add :: Server -> Key -> Value -> Flags -> Expiration -> IO (Maybe Version)
replace :: Server -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe Version)
delete :: Server -> Key -> Version -> IO Bool
increment :: Server -> Key -> Initial -> Delta -> Expiration -> Version -> IO (Maybe (Word64, Version))
decrement :: Server -> Key -> Initial -> Delta -> Expiration -> Version -> IO (Maybe (Word64, Version))
append :: Server -> Key -> Value -> Version -> IO (Maybe Version)
prepend :: Server -> Key -> Value -> Version -> IO (Maybe Version)

-- | StatResults are a list of key-value pairs.
type StatResults = [(ByteString, ByteString)]
stats :: Server -> Maybe Key -> IO (Maybe StatResults)
flush :: Server -> Maybe Expiration -> IO ()
noop :: Server -> IO ()
version :: Server -> IO ByteString
quit :: Server -> IO ()


-- | Handles a group of connections to different memcached servers.
module Database.Memcache.Cluster

-- | A memcached cluster client.
data Cluster

-- | Establish a new connection to a group of memcached servers.
newCluster :: [ServerSpec] -> Options -> IO Cluster

-- | ServerSpec specifies a server configuration to connect to.
data ServerSpec
ServerSpec :: HostName -> PortNumber -> Authentication -> ServerSpec
[ssHost] :: ServerSpec -> HostName
[ssPort] :: ServerSpec -> PortNumber
[ssAuth] :: ServerSpec -> Authentication

-- | Provides a default value for a server cconnection config.
defaultServerSpec :: ServerSpec

-- | Options specifies how a memcached cluster should be configured.
data Options
Options :: !FailureMode -> !FailureMode -> !Int -> Options
[optsCmdFailure] :: Options -> !FailureMode
[optsServerFailure] :: Options -> !FailureMode
[optsServerRetries] :: Options -> !Int

-- | Provides recommended default for a cluster Options.
defaultOptions :: Options

-- | Run a memcached operation against a server that maps to the key given
--   in the cluster.
keyedOp :: Maybe a -> Cluster -> Key -> (Server -> IO a) -> IO a

-- | Run a memcached operation against any single server in the cluster.
anyOp :: Maybe a -> Cluster -> (Server -> IO a) -> IO a

-- | Run a memcached operation against all servers in the cluster.
allOp :: Maybe a -> Cluster -> (Server -> IO a) -> IO [(Server, a)]
instance GHC.Show.Show Database.Memcache.Cluster.Cluster
instance GHC.Show.Show Database.Memcache.Cluster.FailureMode
instance GHC.Classes.Eq Database.Memcache.Cluster.FailureMode


-- | A memcached client. Supports the binary protocol (only) and SASL
--   authentication.
--   
--   A client can connect to a single memcached server or a cluster of
--   them. In the later case, consistent hashing is used to route requests
--   to the appropriate server.
--   
--   Expected return values (like misses) are returned as part of the
--   return type, while unexpected errors are thrown as exceptions.
module Database.Memcache.Client

-- | Establish a new connection to a group of memcached servers.
newClient :: [ServerSpec] -> Options -> IO Client

-- | A memcached client, connected to a collection of memcached servers.
type Client = Cluster

-- | ServerSpec specifies a server configuration to connect to.
data ServerSpec
ServerSpec :: HostName -> PortNumber -> Authentication -> ServerSpec
[ssHost] :: ServerSpec -> HostName
[ssPort] :: ServerSpec -> PortNumber
[ssAuth] :: ServerSpec -> Authentication

-- | Provides a default value for a server cconnection config.
defaultServerSpec :: ServerSpec

-- | Options specifies how a memcached cluster should be configured.
data Options
Options :: !FailureMode -> !FailureMode -> !Int -> Options
[optsCmdFailure] :: Options -> !FailureMode
[optsServerFailure] :: Options -> !FailureMode
[optsServerRetries] :: Options -> !Int

-- | Provides recommended default for a cluster Options.
defaultOptions :: Options

-- | SASL Authentication information for a server.
data Authentication
Auth :: !Username -> !Password -> Authentication
[username] :: Authentication -> !Username
[password] :: Authentication -> !Password
NoAuth :: Authentication

-- | Username for authentication.
type Username = ByteString

-- | Password for authentication.
type Password = ByteString

-- | Gracefully close a connection to a memcached cluster.
quit :: Cluster -> IO ()

-- | Retrieve the value for the given key from memcache.
get :: Cluster -> Key -> IO (Maybe (Value, Flags, Version))

-- | Get-and-touch: Retrieve the value for the given key from memcache, and
--   also update the stored key-value pairs expiration time at the server.
gat :: Cluster -> Key -> Expiration -> IO (Maybe (Value, Flags, Version))

-- | Update the expiration time of a stored key-value pair, returning its
--   version identifier.
touch :: Cluster -> Key -> Expiration -> IO (Maybe Version)

-- | Store a new (or overwrite exisiting) key-value pair, returning its
--   version identifier.
set :: Cluster -> Key -> Value -> Flags -> Expiration -> IO Version

-- | Store a key-value pair, but only if the version specified by the
--   client matches the version of the key-value pair at the server. The
--   version identifier of the stored key-value pair is returned, or if the
--   version match fails, <a>Nothing</a> is returned.
set' :: Cluster -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe Version)

-- | Store a new key-value pair, returning it's version identifier. If the
--   key-value pair already exists, then fail (return <a>Nothing</a>).
add :: Cluster -> Key -> Value -> Flags -> Expiration -> IO (Maybe Version)

-- | Update the value of an existing key-value pair, returning it's new
--   version identifier. If the key doesn't already exist, the fail and
--   return Nothing.
replace :: Cluster -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe Version)

-- | Delete a key-value pair at the server, returning true if successful.
delete :: Cluster -> Key -> Version -> IO Bool

-- | Remove (delete) all currently stored key-value pairs from the cluster.
flush :: Cluster -> Maybe Expiration -> IO ()

-- | Increment a numeric value stored against a key, returning the
--   incremented value and the version identifier of the key-value pair.
increment :: Cluster -> Key -> Initial -> Delta -> Expiration -> Version -> IO (Maybe (Word64, Version))

-- | Decrement a numeric value stored against a key, returning the
--   decremented value and the version identifier of the key-value pair.
decrement :: Cluster -> Key -> Initial -> Delta -> Expiration -> Version -> IO (Maybe (Word64, Version))

-- | Append a value to an existing key-value pair, returning the new
--   version identifier of the key-value pair when successful.
append :: Cluster -> Key -> Value -> Version -> IO (Maybe Version)

-- | Prepend a value to an existing key-value pair, returning the new
--   version identifier of the key-value pair when successful.
prepend :: Cluster -> Key -> Value -> Version -> IO (Maybe Version)

-- | Version returns the version string of the memcached cluster. We just
--   query one server and assume all servers in the cluster are the same
--   version.
version :: Cluster -> IO ByteString

-- | Return statistics on the stored key-value pairs at each server in the
--   cluster.
stats :: Cluster -> Maybe Key -> IO [(Server, Maybe StatResults)]

-- | StatResults are a list of key-value pairs.
type StatResults = [(ByteString, ByteString)]

-- | Exceptions that may be thrown by Memcache. These are expected error
--   codes returned by a memcached server.
data MemcacheError
MemErrNoKey :: MemcacheError
MemErrKeyExists :: MemcacheError
MemErrValueTooLarge :: MemcacheError
MemErrInvalidArgs :: MemcacheError
MemErrStoreFailed :: MemcacheError
MemErrValueNonNumeric :: MemcacheError
MemErrUnknownCmd :: MemcacheError
MemErrOutOfMemory :: MemcacheError
MemErrAuthFail :: MemcacheError

-- | Errors that occur between the client and server in communicating.
--   These are unexpected exceptions, such as network failures or garbage
--   data.
data ClientError
NotEnoughBytes :: ClientError