-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A memcached client library. -- -- A client library for a Memcached cluster. Memcached is an in-memory -- key-value store typically used as a distributed and shared cache. -- Clients connect to a group of Memcached servers and perform -- out-of-band caching for things like SQL results, rendered pages, or -- third-party APIs. -- -- 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. Timeouts, retrying failed operations, and failover -- to a different server are all supported. -- -- Complete coverage of the Memcached protocol is provided except for -- multi-get and other pipelined operations. -- -- Basic usage is: -- -- 
--   import qualified Database.Memcache.Client as M
--   
--   mc <- M.newClient [M.ServerSpec "localhost" 11211 M.NoAuth] M.def
--   M.set mc "key" "value" 0 0
--   v <- M.get mc "key"
--
-- -- You should only need to import Database.Memcache.Client, but -- for now other modules are exposed. @package memcache @version 0.2.0.1 -- | Stores the various types needed by Memcached. 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 -- | The status (success or error) of a Memcached operation returned in a -- Response. data Status -- | Operation successful. NoError :: Status -- | Key not found. ErrKeyNotFound :: Status -- | Key exists when not expected. ErrKeyExists :: Status -- | Value too large to store at server. ErrValueTooLarge :: Status -- | Invalid arguments for operation. ErrInvalidArgs :: Status -- | Key-Value pair not stored at server (internal error). ErrItemNotStored :: Status -- | Value not numeric when increment or decrement requested. ErrValueNonNumeric :: Status -- | Server doesn't know requested command. ErrUnknownCommand :: Status -- | Server out of memory. ErrOutOfMemory :: Status -- | SASL authentication failed. SaslAuthFail :: Status -- | SASL authentication requires more steps. SaslAuthContinue :: Status -- | Memcached packet header (for both Request and Response). 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 mEMCACHE_HEADER_SIZE :: Int data PktType PktRequest :: PktType PktResponse :: PktType 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 -- | Raw request is custom requests, dangerous as no corresponding raw -- response... -- | Warning: This is dangerous; no future compatability guaranteed ReqRaw :: Word8 -> (Maybe Key) -> (Maybe Value) -> SERaw -> OpRequest data SESet SESet :: Flags -> Expiration -> SESet data SEIncr SEIncr :: Initial -> Delta -> Expiration -> SEIncr data SETouch SETouch :: Expiration -> SETouch data SERaw SERaw :: Builder -> Int -> SERaw -- | Noop request. emptyReq :: Request -- | Memcached response packet. 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 -- | Noop response. emptyRes :: Response instance GHC.Show.Show Database.Memcache.Types.Response instance GHC.Classes.Eq Database.Memcache.Types.Response instance GHC.Show.Show Database.Memcache.Types.Header instance GHC.Classes.Eq Database.Memcache.Types.Header 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.Show.Show Database.Memcache.Types.PktType instance GHC.Classes.Eq Database.Memcache.Types.PktType instance GHC.Show.Show Database.Memcache.Types.Authentication instance GHC.Classes.Eq Database.Memcache.Types.Authentication instance GHC.Show.Show Database.Memcache.Types.SERaw instance GHC.Classes.Eq Database.Memcache.Types.SERaw -- | Memcached related errors and exception handling. module Database.Memcache.Errors -- | All exceptions that a Memcached client may throw. data MemcacheError -- | Memcached operation error. OpError :: Status -> MemcacheError -- | Error occuring on client side. ClientError :: ClientError -> MemcacheError -- | Errors occurring communicating with Memcached server. ProtocolError :: ProtocolError -> MemcacheError -- | The status (success or error) of a Memcached operation returned in a -- Response. data Status -- | Operation successful. NoError :: Status -- | Key not found. ErrKeyNotFound :: Status -- | Key exists when not expected. ErrKeyExists :: Status -- | Value too large to store at server. ErrValueTooLarge :: Status -- | Invalid arguments for operation. ErrInvalidArgs :: Status -- | Key-Value pair not stored at server (internal error). ErrItemNotStored :: Status -- | Value not numeric when increment or decrement requested. ErrValueNonNumeric :: Status -- | Server doesn't know requested command. ErrUnknownCommand :: Status -- | Server out of memory. ErrOutOfMemory :: Status -- | SASL authentication failed. SaslAuthFail :: Status -- | SASL authentication requires more steps. SaslAuthContinue :: Status -- | Errors that occur on the client. data ClientError -- | All servers are currently marked failed. NoServersReady :: ClientError -- | Timeout occurred sending request to server. Timeout :: ClientError -- | Errors related to Memcached protocol and bytes on the wire. data ProtocolError -- | Received an unknown response packet. UnknownPkt :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Unknown Memcached operation. UnknownOp :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Unknown Memcached status field value. UnknownStatus :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Unexpected length of a Memcached field (extras, key, or value). BadLength :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Response packet is for a different operation than expected. WrongOp :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Network socket closed without receiving enough bytes. UnexpectedEOF :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Convert a status to MemcacheError exception. throwStatus :: Status -> IO a -- | Create a properly formatted WrongOp protocol error. wrongOp :: Response -> String -> MemcacheError instance GHC.Show.Show Database.Memcache.Errors.MemcacheError instance GHC.Classes.Eq Database.Memcache.Errors.MemcacheError instance GHC.Show.Show Database.Memcache.Errors.ProtocolError instance GHC.Classes.Eq Database.Memcache.Errors.ProtocolError instance GHC.Show.Show Database.Memcache.Errors.ClientError instance GHC.Classes.Eq Database.Memcache.Errors.ClientError instance GHC.Exception.Exception Database.Memcache.Errors.MemcacheError -- | Handles a single Memcached connection, sending and receiving requests. module Database.Memcache.Socket -- | Represents a socket. The fields are, respectively: -- -- -- -- If you are calling the MkSocket constructor directly you should -- ensure you have called withSocketsDo. data Socket :: * data Request Req :: OpRequest -> Word32 -> Version -> Request [reqOp] :: Request -> OpRequest [reqOpaque] :: Request -> Word32 [reqCas] :: Request -> Version -- | Memcached response packet. data Response Res :: OpResponse -> Status -> Word32 -> Version -> Response [resOp] :: Response -> OpResponse [resStatus] :: Response -> Status [resOpaque] :: Response -> Word32 [resCas] :: Response -> Version -- | Send a request to the Memcached server. send :: Socket -> Request -> IO () -- | Retrieve a single response from the Memcached server. FIXME: read into -- buffer to minimize read syscalls recv :: Socket -> IO Response -- | Serialize a request to a ByteString Builder. szRequest :: Request -> Builder -- | Serialize a response to a ByteString Builder. szResponse :: Response -> Builder -- | Deserialize a Header from a ByteString. dzHeader :: PktType -> Get Header -- | Deserialize a Response body. dzResponse :: Header -> ByteString -> Response -- | SASL authentication support for Memcached. module Database.Memcache.SASL -- | 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 -- | Perform SASL authentication with the server. authenticate :: Socket -> Authentication -> IO () -- | Handles the connections between a Memcached client and a single -- server. -- -- Memcached expected errors (part of protocol) are returned in the -- Response, unexpected errors (e.g., network failure) are thrown as -- exceptions. While the Server datatype supports a failed and -- failedAt flag for managing retries, it's up to consumers to -- use this. module Database.Memcache.Server -- | Memcached server connection. data Server -- | Create a new Memcached server 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 send -- and recv. 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 -- | Handles a group of connections to different Memcached servers. -- -- We use consistent hashing to choose which server to route a request -- to. On an error, we mark the server as failed and remove it -- temporarialy from the set of servers available. module Database.Memcache.Cluster -- | Memcached cluster. data Cluster -- | ServerSpec specifies a server configuration for connection. data ServerSpec ServerSpec :: HostName -> PortNumber -> Authentication -> ServerSpec -- | Hostname of server to connect to. [ssHost] :: ServerSpec -> HostName -- | Port number server is running on. [ssPort] :: ServerSpec -> PortNumber -- | Authentication values to use for SASL authentication with this server. [ssAuth] :: ServerSpec -> Authentication -- | Options specifies how a Memcached cluster should be configured. data Options Options :: Retries -> Milli -> Milli -> Milli -> Options -- | Number of times to retry an operation on failure. If consecutive -- failures exceed this value for a server, we mark it as down and -- failover to a different server for the next operation. -- -- Default is 2. [optsServerRetries] :: Options -> Retries -- | After an operation has failed, how long to wait before retrying it -- while still within the optsServerRetries count? -- -- Default is 200ms. [optsFailRetryDelay] :: Options -> Milli -- | How long to wait after a server has been marked down, before trying to -- use it again. -- -- Default is 1500ms. [optsDeadRetryDelay] :: Options -> Milli -- | How long to wait for an operation to complete before considering it -- failed. -- -- Default is 750ms. [optsServerTimeout] :: Options -> Milli -- | Establish a new connection to a group of Memcached servers. newCluster :: [ServerSpec] -> Options -> IO Cluster -- | Number of times to retry an operation before considering it failed. type Retries = Int -- | Run a Memcached operation against a particular server, handling any -- failures that occur, retrying the specified number of times. keyedOp :: Cluster -> Key -> Request -> IO Response -- | Run a Memcached operation against any single server in the cluster, -- handling any failures that occur, retrying the specified number of -- times. anyOp :: Cluster -> Request -> IO Response -- | Run a Memcached operation against all servers in the cluster, handling -- any failures that occur, retrying the specified number of times. allOp :: Cluster -> Request -> IO [(Server, Response)] -- | Run a Memcached operation against all servers in the cluster, handling -- any failures that occur, retrying the specified number of times. -- Similar to anyOp but allows more flexible interaction with the -- Server than a single request and response. allOp' :: Cluster -> (Server -> IO a) -> IO [(Server, a)] instance GHC.Show.Show Database.Memcache.Cluster.Cluster instance GHC.Classes.Eq Database.Memcache.Cluster.Cluster instance GHC.Show.Show Database.Memcache.Cluster.Options instance GHC.Classes.Eq Database.Memcache.Cluster.Options instance GHC.Show.Show Database.Memcache.Cluster.ServerSpec instance GHC.Classes.Eq Database.Memcache.Cluster.ServerSpec instance Data.Default.Class.Default Database.Memcache.Cluster.ServerSpec instance Data.Default.Class.Default Database.Memcache.Cluster.Options -- | A Memcached client. Memcached is an in-memory key-value store -- typically used as a distributed and shared cache. Clients connect to a -- group of Memcached servers and perform out-of-band caching for things -- like SQL results, rendered pages, or third-party APIs. -- -- 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. The binary Memcached protocol is -- used and SASL authentication is supported. -- -- Expected return values (like misses) are returned as part of the -- return type, while unexpected errors are thrown as exceptions. -- Exceptions are either of type MemcacheError or an IO -- exception thrown by the network. -- -- We support the following logic for handling failure in operations: -- -- -- -- Some of this behavior can be configured through the Options -- data type. We also have the following concepts exposed by Memcached: -- -- -- -- Usage is roughly as follows: -- -- 
--   module Main where
--   
--   import qualified Database.Memcache.Client as M
--   
--   main = do
--       -- use default values: connects to localhost:11211
--       mc <- M.newClient [M.def] M.def
--   
--       -- store and then retrieve a key-value pair
--       M.set mc "key" "value" 0 0
--       v' <- M.get mc "key"
--       case v' of
--           Nothing        -> putStrLn "Miss!"
--           Just (v, _, _) -> putStrLn $ "Hit: " + show v
--
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 for connection. data ServerSpec ServerSpec :: HostName -> PortNumber -> Authentication -> ServerSpec -- | Hostname of server to connect to. [ssHost] :: ServerSpec -> HostName -- | Port number server is running on. [ssPort] :: ServerSpec -> PortNumber -- | Authentication values to use for SASL authentication with this server. [ssAuth] :: ServerSpec -> Authentication -- | Options specifies how a Memcached cluster should be configured. data Options Options :: Retries -> Milli -> Milli -> Milli -> Options -- | Number of times to retry an operation on failure. If consecutive -- failures exceed this value for a server, we mark it as down and -- failover to a different server for the next operation. -- -- Default is 2. [optsServerRetries] :: Options -> Retries -- | After an operation has failed, how long to wait before retrying it -- while still within the optsServerRetries count? -- -- Default is 200ms. [optsFailRetryDelay] :: Options -> Milli -- | How long to wait after a server has been marked down, before trying to -- use it again. -- -- Default is 1500ms. [optsDeadRetryDelay] :: Options -> Milli -- | How long to wait for an operation to complete before considering it -- failed. -- -- Default is 750ms. [optsServerTimeout] :: Options -> Milli -- | 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 -- | The default value for this type. def :: Default a => a -- | Gracefully close a connection to a Memcached cluster. quit :: Cluster -> IO () -- | Retrieve the value for the given key from Memcached. get :: Cluster -> Key -> IO (Maybe (Value, Flags, Version)) -- | Get-and-touch: Retrieve the value for the given key from Memcached, -- and also update the stored key-value pairs expiration time at the -- server. Use an expiration value of 0 to store forever. gat :: Cluster -> Key -> Expiration -> IO (Maybe (Value, Flags, Version)) -- | Update the expiration time of a stored key-value pair, returning its -- version identifier. Use an expiration value of 0 to store -- forever. touch :: Cluster -> Key -> Expiration -> IO (Maybe Version) -- | Store a new (or overwrite exisiting) key-value pair, returning its -- version identifier. Use an expiration value of 0 to store -- forever. 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, Nothing is returned. Use an expiration -- value of 0 to store forever. cas :: 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 Nothing). Use -- an expiration value of 0 to store forever. 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. Use an expiration value of 0 to store -- forever. replace :: Cluster -> Key -> Value -> Flags -> Expiration -> Version -> IO (Maybe Version) -- | Increment a numeric value stored against a key, returning the -- incremented value and the version identifier of the key-value pair. -- Use an expiration value of 0 to store forever. 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. -- Use an expiration value of 0 to store forever. 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) -- | 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. -- The expiration value can be used to cause this flush to occur in the -- future rather than immediately. flush :: Cluster -> Maybe Expiration -> IO () -- | StatResults are a list of key-value pairs. type StatResults = [(ByteString, ByteString)] -- | Return statistics on the stored key-value pairs at each server in the -- cluster. The optional key can be used to select a different set of -- statistics from the server than the default. Most Memcached servers -- support "items", "slabs" or "settings". stats :: Cluster -> Maybe Key -> IO [(Server, Maybe StatResults)] -- | 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 -- | All exceptions that a Memcached client may throw. data MemcacheError -- | Memcached operation error. OpError :: Status -> MemcacheError -- | Error occuring on client side. ClientError :: ClientError -> MemcacheError -- | Errors occurring communicating with Memcached server. ProtocolError :: ProtocolError -> MemcacheError -- | The status (success or error) of a Memcached operation returned in a -- Response. data Status -- | Operation successful. NoError :: Status -- | Key not found. ErrKeyNotFound :: Status -- | Key exists when not expected. ErrKeyExists :: Status -- | Value too large to store at server. ErrValueTooLarge :: Status -- | Invalid arguments for operation. ErrInvalidArgs :: Status -- | Key-Value pair not stored at server (internal error). ErrItemNotStored :: Status -- | Value not numeric when increment or decrement requested. ErrValueNonNumeric :: Status -- | Server doesn't know requested command. ErrUnknownCommand :: Status -- | Server out of memory. ErrOutOfMemory :: Status -- | SASL authentication failed. SaslAuthFail :: Status -- | SASL authentication requires more steps. SaslAuthContinue :: Status -- | Errors that occur on the client. data ClientError -- | All servers are currently marked failed. NoServersReady :: ClientError -- | Timeout occurred sending request to server. Timeout :: ClientError -- | Errors related to Memcached protocol and bytes on the wire. data ProtocolError -- | Received an unknown response packet. UnknownPkt :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Unknown Memcached operation. UnknownOp :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Unknown Memcached status field value. UnknownStatus :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Unexpected length of a Memcached field (extras, key, or value). BadLength :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Response packet is for a different operation than expected. WrongOp :: String -> ProtocolError [protocolError] :: ProtocolError -> String -- | Network socket closed without receiving enough bytes. UnexpectedEOF :: String -> ProtocolError [protocolError] :: ProtocolError -> String