Commit 430da3fe authored by Shane Snyder's avatar Shane Snyder

first cut at mobject header

parent 3e854c72
/*
* (C) 2017 The University of Chicago
*
* See COPYRIGHT in top-level directory.
*/
#ifndef __MOBJECT_STORE
#define __MOBJECT_STORE
#ifdef __cplusplus
extern "C" {
#endif
// derived from: http://docs.ceph.com/docs/master/rados/api/librados/
/* KEY TERMS
*
* Pool:
* - an object container providing separate namespaces for objects
* - pools can have different placement & replication strategies
*
* Placement group (PG):
* - Groups of objects within a pool that share the same OSDs.
*
* CRUSH:
* - Data placement algorithm for RADOS objects, mapping OIDs to PGs.
*/
/* ASSUMPTIONS/QUESTIONS
* - Initially we enforce one global pool for each mobject store instance for simplicity.
*
* - We will not implement any replication.
*
* - RADOS seems to expose object versions, but I only see them in the 'object operation' portion of their API, which is big and awkward (i.e., would love to not implement that).
*
* - Do we need any of the following from RADOS:
* - async I/O operations?
* - cursor stuff?
* - snapshots?
* - extended attributes?
*
* - RADOS API includes a watch/notify API that sounds like something we could build on top of a generic SSG pub-sub service, if we wanted.
*
*/
/* opaque handle for interacting with a mobject cluster */
typedef struct mobject_store_handle *mobject_store_t;
/* opaque mobject store i/o context type */
typedef struct mobject_store_ioctx *mobject_store_ioctx_t;
extern const char *mobject_global_pool;
/*****************************************
* mobject store setup/teardown routines *
*****************************************/
/**
* Create a handle to a mobject cluster.
*
* @param[in/out] cluster pointer to store mobject cluster handle at
* @returns 0 on success, negative error code on failure
*
* NOTES:
* - from rados_create(rados_t * cluster, const char *const user_id)
* - drop user_id from API
* - may eventually need conf. file, env variable checking, etc.
*/
int mobject_store_create(
mobject_store_t *cluster);
/**
* Connect to a mobject cluster.
*
* @param[in] cluster handle to mobject cluster
* @returns 0 on success, negative error code on failure
*/
int mobject_store_connect(
mobject_store_t cluster);
/**
* Disconnects from a mobject cluster and destroys the cluster handle.
*
* @param[in] cluster handle to mobject cluster
*/
void mobject_store_shutdown(
mobject_store_t cluster);
/*****************************************************
* mobject store i/o context setup/teardown routines *
*****************************************************/
/**
* Create an I/O context for a mobject cluster.
*
* @param[in] cluster handle to mobject cluster
* @param[in] pool_name name of the pool
* @param[in/out] ioctx pointer to store the io context at
* @returns 0 on success, negative error code on failure
*
* NOTES:
* - only one global pool exists and is defined at the top of this header
*/
int mobject_store_ioctx_create(
mobject_store_t cluster,
const char * pool_name,
mobject_store_ioctx_t *ioctx);
/**
* Destroy an I/O context.
*
* @param[in] ioctx io context to destroy
*/
void mobject_store_ioctx_destroy(
mobject_store_ioctx_t ioctx);
/******************************
* mobject store i/o routines *
******************************/
/**
* Write @p len bytes from @p buf into object @p oid starting at offset @p off.
*
* @param[in] ioctx io context
* @param[in] oid name of the object
* @param[in] buf buffer containing data to write
* @param[in] len length of the data
* @param[in] off byte offset within object to write at
* @returns 0 on success, negative error code on failure
*/
mobject_store_write(
mobject_store_ioctx_t ioctx,
const char * oid,
const char * buf,
size_t len,
uint64_t off);
/**
* Write @p len bytes from @p buf into object @p oid. The object is filled with
* the provided data; if the object exists, it is truncated first.
*
* @param[in] ioctx io context
* @param[in] oid name of the object
* @param[in] buf buffer containing data to write
* @param[in] len length of the data
* @returns 0 on success, negative error code on failure
*/
mobject_store_write_full(
mobject_store_ioctx_t ioctx,
const char * oid,
const char * buf,
size_t len);
/**
* Append @p len bytes from @p buf into object @p oid.
*
* @param[in] ioctx io context
* @param[in] oid name of the object
* @param[in] buf buffer containing data to append
* @param[in] len length of the data
* @returns 0 on success, negative error code on failure
*/
mobject_store_append(
mobject_store_ioctx_t ioctx,
const char * oid,
const char * buf,
size_t len);
/**
* Read @p len bytes from object @p oid starting at offset @p off into @p buf.
*
* @param[in] ioctx io context
* @param[in] oid name of the object
* @param[in] buf buffer containing data to write
* @param[in] len length of the data
* @param[in] off byte offset within object to write at
* @returns 0 on success, negative error code on failure
*/
mobject_store_read(
mobject_store_ioctx_t ioctx,
const char * oid,
const char * buf,
size_t len,
uint64_t off);
/**
* Deletes an object.
*
* @param[in] ioctx io context
* @param[in] oid name of the object
* @returns 0 on success, negative error code on failure
*/
mobject_store_remove(
mobject_store_ioctx_t ioctx,
const char * oid);
/**
* Resize an object. If this enlarges the object, the new area is logically
* filled with zeroes. If this shrinks the object, the excess data is removed.
*
* @param[in] ioctx io context
* @param[in] oid name of the object
* @param[in] size new size of the object
* @returns 0 on success, negative error code on failure
*/
mobject_store_trunc(
mobject_store_ioctx_t ioctx,
const char * oid,
uint64_t size);
/**
* Get object stats.
*
* @param[in] ioctx io context
* @param[in] oid name of the object
* @param[in/out] psize pointer to store object size
* @param[in/out] pmtime pointer to store object modification time
* @returns 0 on success, negative error code on failure
*/
mobject_store_stat(
mobject_store_ioctx_t ioctx,
const char * oid,
uint64_t * psize,
time_t * pmtime);
#ifdef __cplusplus
}
#endif
#endif /* __MOBJECT_STORE */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment