System.Rados.Base

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.

Type definitions

data Connection

A connection to a rados cluster, required to get an IOContext

Instances

MonadReader Connection Connection

data Completion

A handle to query the status of an asynchronous action

Instances

Eq Completion

Ord Completion

data IOContext

An IO context with a rados pool.

Instances

MonadReader IOContext Async

MonadReader IOContext Pool

data TimeVal

Constructors

TimeVal

Fields

seconds :: CLong

microseconds :: CLong

Instances

Eq TimeVal

Num TimeVal

Show TimeVal

Storable TimeVal

data LockFlag

Connecting

withConnection :: Maybe ByteString -> (Connection -> IO a) -> IO a

Perform an action given a Connection, cleans up with bracket

 withConnection Nothing $ c -> do
   confReadFile c "/etc/config"
   doStuff

newConnection :: Maybe ByteString -> IO Connection

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 ()

Clean up a cluster handle.

Calls: http://ceph.com/docs/master/rados/api/librados/#rados_shutdown

confReadFile :: Connection -> FilePath -> IO (Maybe RadosError)

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)

confParseEnv :: Connection -> IO (Maybe RadosError)

connect :: Connection -> IO ()

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

Perform an action given an IOContext, cleans up with bracket withConnection Nothing $ c -> do confParseArgv c withIOContext c pool_a ctx -> syncRemove ctx an_object

newIOContext :: Connection -> ByteString -> IO IOContext

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 ()

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)

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)

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)

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)

Append a ByteString to IOContext and object id.

Returns the number of bytes written.

syncRemove :: IOContext -> ByteString -> IO (Maybe RadosError)

Delete an object from IOContext by ID.

syncStat :: IOContext -> ByteString -> IO (Either RadosError (Word64, EpochTime))

Asynchronous

newCompletion :: IO Completion

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 ()

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 ()

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)

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)

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)

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)

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))

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)

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)

Locking

Don't bother

exclusiveLock

Arguments

:: RealFrac duration

=> IOContext

-> ByteString

oid

-> ByteString

name

-> ByteString

cookie

-> ByteString

desc

-> Maybe duration

-> [LockFlag]

-> IO ()

Make an exclusive lock

sharedLock

Arguments

:: RealFrac duration

=> IOContext

-> ByteString

oid

-> ByteString

name

-> ByteString

cookie

-> ByteString

tag

-> ByteString

desc

-> Maybe duration

-> [LockFlag]

-> IO ()

Make a shared lock

unlock

Arguments

:: IOContext

-> ByteString

oid

-> ByteString

name

-> ByteString

cookie

-> IO (Maybe RadosError)

Release a lock of any sort

idempotent :: LockFlag