Copyright | (c) 2010-2014 Anchor |
---|---|
License | BSD-3 |
Maintainer | Christian Marie <christian@ponies.io> |
Stability | experimental |
Portability | non-portable |
Safe Haskell | None |
Language | Haskell2010 |
Bindings to librados, covers async read/writes, locks and atomic writes (build flag).
These are underlying functions used for the monadic implementation System.Rados.
These can be a bit of a pain to use as they are thin wrappers around the C API, you will need to do a lot of cleanup yourself.
- data Connection
- data Completion
- data IOContext
- data ListContext
- data TimeVal = TimeVal {
- seconds :: CLong
- microseconds :: CLong
- data LockFlag
- data RadosError
- withConnection :: Maybe ByteString -> (Connection -> IO a) -> IO a
- newConnection :: Maybe ByteString -> IO Connection
- cleanupConnection :: Connection -> IO ()
- confReadFile :: Connection -> FilePath -> IO (Maybe RadosError)
- confParseArgv :: Connection -> IO (Maybe RadosError)
- confParseEnv :: Connection -> IO (Maybe RadosError)
- connect :: Connection -> IO ()
- withIOContext :: Connection -> ByteString -> (IOContext -> IO a) -> IO a
- newIOContext :: Connection -> ByteString -> IO IOContext
- cleanupIOContext :: IOContext -> IO ()
- syncWrite :: IOContext -> ByteString -> Word64 -> ByteString -> IO (Maybe RadosError)
- syncWriteFull :: IOContext -> ByteString -> ByteString -> IO (Maybe RadosError)
- syncRead :: IOContext -> ByteString -> Word64 -> Word64 -> IO (Either RadosError ByteString)
- syncAppend :: IOContext -> ByteString -> ByteString -> IO (Maybe RadosError)
- syncRemove :: IOContext -> ByteString -> IO (Maybe RadosError)
- syncStat :: IOContext -> ByteString -> IO (Either RadosError (Word64, EpochTime))
- newCompletion :: IO Completion
- waitForComplete :: Completion -> IO ()
- waitForSafe :: Completion -> IO ()
- asyncWrite :: IOContext -> Completion -> ByteString -> Word64 -> ByteString -> IO (Either RadosError Int)
- asyncWriteFull :: IOContext -> Completion -> ByteString -> ByteString -> IO (Either RadosError Int)
- asyncRead :: IOContext -> Completion -> ByteString -> Word64 -> Word64 -> IO (Either RadosError ByteString)
- asyncAppend :: IOContext -> Completion -> ByteString -> ByteString -> IO (Either RadosError Int)
- asyncStat :: IOContext -> Completion -> ByteString -> IO (Either RadosError (ForeignPtr Word64, ForeignPtr CTime))
- asyncRemove :: IOContext -> Completion -> ByteString -> IO (Either RadosError Int)
- getAsyncError :: Completion -> IO (Either RadosError Int)
- withList :: IOContext -> (ListContext -> IO a) -> IO a
- nextObject :: ListContext -> IO (Maybe ByteString)
- objects :: IOContext -> IO [ByteString]
- unsafeObjects :: IOContext -> IO [ByteString]
- openList :: IOContext -> IO ListContext
- closeList :: ListContext -> IO ()
- newCookie :: IO ByteString
- exclusiveLock :: RealFrac duration => IOContext -> ByteString -> ByteString -> ByteString -> ByteString -> Maybe duration -> [LockFlag] -> IO ()
- sharedLock :: RealFrac duration => IOContext -> ByteString -> ByteString -> ByteString -> ByteString -> ByteString -> Maybe duration -> [LockFlag] -> IO ()
- unlock :: IOContext -> ByteString -> ByteString -> ByteString -> IO (Maybe RadosError)
- idempotent :: LockFlag
- missingOK :: Maybe RadosError -> IO ()
Type definitions
data Connection Source
A connection to a rados cluster, required to get an IOContext
data Completion Source
A handle to query the status of an asynchronous action
An IO context with a rados pool.
data ListContext Source
A pool listing handle
TimeVal | |
|
data RadosError Source
An error indicated by librados, usually in the form of a negative return value
Connecting
withConnection :: Maybe ByteString -> (Connection -> IO a) -> IO a Source
Perform an action given a Connection
, cleans up with bracket
withConnection Nothing $ c -> do confReadFile c "/etc/config" doStuff
newConnection :: Maybe ByteString -> IO Connection Source
Attempt to create a new 'Connection, taking an optional id. You must run cleanupConnection on the handle when you are done with it.
h <- newConnection Nothing h' <- newConnection $ Just "admin" cleanupConnection h cleanupConnection h'
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_create
cleanupConnection :: Connection -> IO () Source
Clean up a cluster handle.
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_shutdown
confReadFile :: Connection -> FilePath -> IO (Maybe RadosError) Source
Load a config specified by FilePath
into a given 'Connection.
h <- newConnection Nothing confReadFile h "/etc/config"
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_conf_read_file
confParseArgv :: Connection -> IO (Maybe RadosError) Source
confParseEnv :: Connection -> IO (Maybe RadosError) Source
connect :: Connection -> IO () Source
Attempt to connect a configured 'Connection.
h <- newConnection Nothing confReadFile h "etcconfig" connect h
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_connect
Writing
withIOContext :: Connection -> ByteString -> (IOContext -> IO a) -> IO a Source
newIOContext :: Connection -> ByteString -> IO IOContext Source
Attempt to create a new IOContext
, requires a valid Connection
and
pool name.
h <- newConnection Nothing h ctx <- newIOContext h "thing" cleanupIOContext ctx cleanupConnection h
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_ioctx_create
cleanupIOContext :: IOContext -> IO () Source
Clean up an IOContext
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_ioctx_destroy
Synchronous
syncWrite :: IOContext -> ByteString -> Word64 -> ByteString -> IO (Maybe RadosError) Source
Write a ByteString
to IOContext
, object id and offset.
... syncWrite IOContext "object_id" 42 "written at offset fourty-two"
syncWriteFull :: IOContext -> ByteString -> ByteString -> IO (Maybe RadosError) Source
Write a ByteString
to IOContext
and object id.
This will replace any existing object at the same IOContext
and object id.
syncRead :: IOContext -> ByteString -> Word64 -> Word64 -> IO (Either RadosError ByteString) Source
Read from IOContext
, object ID and offset n bytes.
There is no async read provided by this binding.
... -- Read 100 bytes into bs from offset 42 bs <- syncRead pool "object_id" 42 100 ...
syncAppend :: IOContext -> ByteString -> ByteString -> IO (Maybe RadosError) Source
Append a ByteString
to IOContext
and object id.
Returns the number of bytes written.
syncRemove :: IOContext -> ByteString -> IO (Maybe RadosError) Source
Delete an object from IOContext
by ID.
syncStat :: IOContext -> ByteString -> IO (Either RadosError (Word64, EpochTime)) Source
Asynchronous
newCompletion :: IO Completion Source
Attempt to create a new Completion
that can be used with async IO actions.
Completion will automatically be cleaned up when it goes out of scope
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_aio_create_completion
waitForComplete :: Completion -> IO () Source
Block until a completion is complete. I.e. the operation associated with the completion is at least in memory on all replicas.
... asyncWrite ctx c "oid" 42 "written at offset fourty-two" putStrLn "Waiting for your bytes to get there..." waitForComplete c putStrLn "I totally wrote it! Maybe."
Calls rados_aio_wait_for_complete: http://ceph.com/docs/master/rados/api/librados/#rados_aio_wait_for_complete
waitForSafe :: Completion -> IO () Source
Block until a completion is safe. I.e. the operation associated with the completion is on stable storage on all replicas.
... waitForSafe c putStrLn "Yeah. Totally did write it. I hope."
Calls rados_aio_wait_for_safe: http://ceph.com/docs/master/rados/api/librados/#rados_aio_wait_for_safe
asyncWrite :: IOContext -> Completion -> ByteString -> Word64 -> ByteString -> IO (Either RadosError Int) Source
From right to left, this function reads as:
Write ByteString bytes to Word64 offset at oid ByteString, notifying this Completion, all within this IOContext
... ctx <- newIOContext h "thing" asyncWrite ctx c "oid" 42 "written at offset fourty-two" putStrLn $ "I wrote " ++ show n ++ " bytes"
Calls rados_aio_write: http://ceph.com/docs/master/rados/api/librados/#rados_aio_write
asyncWriteFull :: IOContext -> Completion -> ByteString -> ByteString -> IO (Either RadosError Int) Source
Same calling convention as asyncWrite, simply omitting an offset. This will truncate any existing object.
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_aio_write_full
asyncRead :: IOContext -> Completion -> ByteString -> Word64 -> Word64 -> IO (Either RadosError ByteString) Source
Returns a ByteString that will be populated when the completion is done.
Attempting to read the ByteString before then is undefined.
The completion will return with the number of bytes actually read.
Due to this complexity, it is recommended to use the monadic bindings when attempting to do async reads.
Calls rados_aio_read: http://ceph.com/docs/master/rados/api/librados/#rados_aio_read
asyncAppend :: IOContext -> Completion -> ByteString -> ByteString -> IO (Either RadosError Int) Source
Same calling convention as asyncWriteFull, simply appends to an object.
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_aio_append
asyncStat :: IOContext -> Completion -> ByteString -> IO (Either RadosError (ForeignPtr Word64, ForeignPtr CTime)) Source
Request the file size and mtime, returns two pointers to the data that will be able to be peeked at when the request is complete.
These pointers will free themselves
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_aio_stat
asyncRemove :: IOContext -> Completion -> ByteString -> IO (Either RadosError Int) Source
Remove an object, calls rados_aio_remove
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_aio_remove
getAsyncError :: Completion -> IO (Either RadosError Int) Source
Pool object enumeration
withList :: IOContext -> (ListContext -> IO a) -> IO a Source
Perform an action with a list context, safely cleaning up with bracket
nextObject :: ListContext -> IO (Maybe ByteString) Source
Return the next OID in the pool, Nothing for end of stream.
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_objects_list_next
objects :: IOContext -> IO [ByteString] Source
Provide a strict list of all objects.
unsafeObjects :: IOContext -> IO [ByteString] Source
Provide a lazy list of all objects. Will only be evaluated as elements are requested. Do not attempt to evaluate this list outside of a valid iocontext. Do not call this again without consuming the whole list, or you will reset the iteration halfway.
openList :: IOContext -> IO ListContext Source
Begin listing objects in pool.
Ensure that you call closeList. Preferably use withList.
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_objects_list_open
closeList :: ListContext -> IO () Source
Close a listing context.
Calls: http://ceph.com/docs/master/rados/api/librados/#rados_objects_list_close
Locking
These functions will be very painful to use without the helpers provided in the Monadic module.
newCookie :: IO ByteString Source
Create a random cookie, useful for shared locks.
:: RealFrac duration | |
=> IOContext | |
-> ByteString | oid |
-> ByteString | name |
-> ByteString | cookie |
-> ByteString | desc |
-> Maybe duration | |
-> [LockFlag] | |
-> IO () |
Make an exclusive lock
:: RealFrac duration | |
=> IOContext | |
-> ByteString | oid |
-> ByteString | name |
-> ByteString | cookie |
-> ByteString | tag |
-> ByteString | desc |
-> Maybe duration | |
-> [LockFlag] | |
-> IO () |
Make a shared lock
:: IOContext | |
-> ByteString | oid |
-> ByteString | name |
-> ByteString | cookie |
-> IO (Maybe RadosError) |
Release a lock of any sort
Helpers
missingOK :: Maybe RadosError -> IO () Source
Take a Maybe Rados Error, if it's anything but NoEntity throw it,