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 ListContext

A pool listing handle

data TimeVal

Constructors

TimeVal

Fields

seconds :: CLong

microseconds :: CLong

Instances

Eq TimeVal

Num TimeVal

Show TimeVal

Storable TimeVal

data LockFlag

data RadosError

An error indicated by librados, usually in the form of a negative return value

Constructors

Unknown

Fields

errno :: Int

Error number (positive)

cFunction :: String

The underlying C function

strerror :: String

The "nice" error message.

NoEntity

Usually returned if a file does not exist

Fields

errno :: Int

Error number (positive)

cFunction :: String

The underlying C function

strerror :: String

The "nice" error message.

Exists

Returned if a file already exists, and should not.

Fields

errno :: Int

Error number (positive)

cFunction :: String

The underlying C function

strerror :: String

The "nice" error message.

Canceled

Returned in the event of a failed atomic transaction

Fields

errno :: Int

Error number (positive)

cFunction :: String

The underlying C function

strerror :: String

The "nice" error message.

Range

A value was out of range, returned when reading or writing from/to invalid regions.

Fields

errno :: Int

Error number (positive)

cFunction :: String

The underlying C function

strerror :: String

The "nice" error message.

User

Fields

message :: String

Instances

Eq RadosError

Ord RadosError

Show RadosError

Exception RadosError

Typeable * RadosError

RadosReader (Object Pool) (Either RadosError)

RadosWriter (Object Pool) (Maybe RadosError)

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)

Pool object enumeration

withList :: IOContext -> (ListContext -> IO a) -> IO a

Perform an action with a list context, safely cleaning up with bracket

nextObject :: ListContext -> IO (Maybe ByteString)

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]

Provide a strict list of all objects.

unsafeObjects :: IOContext -> IO [ByteString]

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

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

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

Create a random cookie, useful for shared locks.

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

Helpers

missingOK :: Maybe RadosError -> IO ()

Take a Maybe Rados Error, if it's anything but NoEntity throw it,