proposed C API for librados

proposed C API for librados

[Colin McCabe]

Hi all,

We're trying to finalize the API for librados for the 0.25 release.
This is the C API we're looking at.

cheers,
Colin


=================================================================
#ifndef CEPH_LIBRADOS_H
#define CEPH_LIBRADOS_H

#ifdef __cplusplus
extern "C" {
#endif

#include <netinet/in.h>
#include <linux/types.h>
#include <string.h>

#ifndef CEPH_OSD_TMAP_SET
#define CEPH_OSD_TMAP_HDR 'h'
#define CEPH_OSD_TMAP_SET 's'
#define CEPH_OSD_TMAP_RM  'r'
#endif

#define LIBRADOS_VER_MAJOR 0
#define LIBRADOS_VER_MINOR 25
#define LIBRADOS_VER_EXTRA 0

#define LIBRADOS_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra)

#define LIBRADOS_VERSION_CODE LIBRADOS_VERSION(LIBRADOS_VER_MAJOR,
LIBRADOS_VER_MINOR, LIBRADOS_VER_EXTRA)

#define LIBRADOS_SUPPORTS_WATCH 1

typedef void *rados_t;
typedef void *rados_pool_t;
typedef void *rados_list_ctx_t;
typedef uint64_t rados_snap_t;

struct rados_pool_stat_t {
  uint64_t num_bytes;    // in bytes
  uint64_t num_kb;       // in KB
  uint64_t num_objects;
  uint64_t num_object_clones;
  uint64_t num_object_copies;  // num_objects * num_replicas
  uint64_t num_objects_missing_on_primary;
  uint64_t num_objects_unfound;
  uint64_t num_objects_degraded;
  uint64_t num_rd, num_rd_kb,num_wr, num_wr_kb;
};

struct rados_statfs_t {
  uint64_t kb, kb_used, kb_avail;
  uint64_t num_objects;
};


void rados_version(int *major, int *minor, int *extra);

/* initialization */
int rados_create(rados_t *cluster, const char * const id);

/* Connect to the cluster */
int rados_connect(rados_t cluster);

/* destroy the cluster instance */
void rados_destroy(rados_t cluster);

/* Config
 *
 * Functions for manipulating the Ceph configuration at runtime.
 * After changing the Ceph configuration, you should call rados_conf_apply to
 * ensure that the changes have been applied.
 */
int rados_conf_read_file(rados_t cluster, const char *path);

/* Sets a configuration value from a string.
 * Returns 0 on success, error code otherwise. */
int rados_conf_set(rados_t cluster, const char *option, const char *value);

/* Reopens the log file.
 * You must do this after changing the logging configuration.
 * It is also good practice to call this from your SIGHUP signal
handler, so that users can send you
 * a SIGHUP to reopen the log.
 */
void rados_reopen_log(rados_t cluster);

/* Returns a configuration value as a string.
 * If len is positive, that is the maximum number of bytes we'll write into the
 * buffer. If len == -1, we'll call malloc() and set *buf.
 * Returns 0 on success, error code otherwise. Returns ENAMETOOLONG if the
 * buffer is too short. */
int rados_conf_get(rados_t cluster, const char *option, char *buf, int len);
int rados_conf_get_alloc(rados_t cluster, const char *option, char **buf);

/* pools */
int rados_pool_open(rados_t cluster, const char *name, rados_pool_t *pool);
int rados_pool_close(rados_pool_t pool);
int rados_pool_lookup(rados_t cluster, const char *name);

int rados_pool_stat(rados_pool_t pool, struct rados_pool_stat_t *stats);

void rados_snap_set_read(rados_pool_t pool, rados_snap_t snap);
int rados_snap_set_write_context(rados_pool_t pool, rados_snap_t seq,
rados_snap_t *snaps, int num_snaps);

int rados_pool_create(rados_t cluster, const char *name);
int rados_pool_create_with_auid(rados_t cluster, const char *name,
uint64_t auid);
int rados_pool_create_with_crush_rule(rados_t cluster, const char
*name, __u8 crush_rule);
int rados_pool_create_with_all(rados_t cluster, const char *name, uint64_t auid,
			       __u8 crush_rule);
int rados_pool_delete(rados_pool_t pool);
int rados_pool_set_auid(rados_pool_t pool, uint64_t auid);

/* objects */
int rados_objects_list_open(rados_pool_t pool, rados_list_ctx_t *ctx);
int rados_objects_list_next(rados_list_ctx_t ctx, const char **entry);
void rados_objects_list_close(rados_list_ctx_t ctx);


/* snapshots */
int rados_pool_snap_create(rados_pool_t pool, const char *snapname);
int rados_pool_snap_remove(rados_pool_t pool, const char *snapname);
int rados_pool_snap_rollback_object(rados_pool_t pool, const char *oid,
			  const char *snapname);
int rados_pool_selfmanaged_snap_create(rados_pool_t pool, uint64_t *snapid);
int rados_pool_selfmanaged_snap_remove(rados_pool_t pool, uint64_t snapid);
int rados_pool_snap_list(rados_pool_t pool, rados_snap_t *snaps, int maxlen);
int rados_pool_snap_lookup(rados_pool_t pool, const char *name,
rados_snap_t *id);
int rados_pool_snap_get_name(rados_pool_t pool, rados_snap_t id, char
*name, int maxlen);

/* sync io */
uint64_t rados_get_last_version(rados_pool_t pool);

int rados_write(rados_pool_t pool, const char *oid, off_t off, const
char *buf, size_t len);
int rados_write_full(rados_pool_t pool, const char *oid, off_t off,
const char *buf, size_t len);
int rados_read(rados_pool_t pool, const char *oid, off_t off, char
*buf, size_t len);
int rados_remove(rados_pool_t pool, const char *oid);
int rados_trunc(rados_pool_t pool, const char *oid, size_t size);

/* attrs */
int rados_getxattr(rados_pool_t pool, const char *o, const char *name,
char *buf, size_t len);
int rados_setxattr(rados_pool_t pool, const char *o, const char *name,
const char *buf, size_t len);
int rados_rmxattr(rados_pool_t pool, const char *o, const char *name);

/* misc */
int rados_stat(rados_pool_t pool, const char *o, uint64_t *psize,
time_t *pmtime);
int rados_tmap_update(rados_pool_t pool, const char *o, const char
*cmdbuf, size_t cmdbuflen);
int rados_exec(rados_pool_t pool, const char *oid, const char *cls,
const char *method,
	       const char *in_buf, size_t in_len, char *buf, size_t out_len);

/* async io */
typedef void *rados_completion_t;
typedef void (*rados_callback_t)(rados_completion_t cb, void *arg);

int rados_aio_create_completion(void *cb_arg, rados_callback_t
cb_complete, rados_callback_t cb_safe,
				rados_completion_t *pc);
int rados_aio_wait_for_complete(rados_completion_t c);
int rados_aio_wait_for_safe(rados_completion_t c);
int rados_aio_is_complete(rados_completion_t c);
int rados_aio_is_safe(rados_completion_t c);
int rados_aio_get_return_value(rados_completion_t c);
uint64_t rados_aio_get_obj_ver(rados_completion_t c);
void rados_aio_release(rados_completion_t c);
int rados_aio_write(rados_pool_t pool, const char *oid,
		    off_t off, const char *buf, size_t len,
		    rados_completion_t completion);
int rados_aio_write_full(rados_pool_t pool, const char *oid,
			 off_t off, const char *buf, size_t len,
			 rados_completion_t completion);
int rados_aio_read(rados_pool_t pool, const char *oid,
		   off_t off, char *buf, size_t len,
		   rados_completion_t completion);

/* watch/notify */
typedef void (*rados_watchcb_t)(uint8_t opcode, uint64_t ver, void *arg);
int rados_watch(rados_pool_t pool, const char *o, uint64_t ver,
uint64_t *handle,
                rados_watchcb_t watchcb, void *arg);
int rados_unwatch(rados_pool_t pool, const char *o, uint64_t handle);
int rados_notify(rados_pool_t pool, const char *o, uint64_t ver);

#ifdef __cplusplus
}
#endif

#endif

Re: proposed C API for librados

[Hannu Valtonen]

On 2/24/11 8:09 AM, Colin McCabe wrote:
Hi,

If you're having a stab at this, could you please add a librados C api 
for listing of pools at the same time. (it's available on the C++ side 
but would be great to have on the C side for Python bindings)


> Hi all,
>
> We're trying to finalize the API for librados for the 0.25 release.
> This is the C API we're looking at.
>
> cheers,
> Colin
>
>
> =================================================================
> #ifndef CEPH_LIBRADOS_H
> #define CEPH_LIBRADOS_H
>
> #ifdef __cplusplus
> extern "C" {
> #endif
>
> #include<netinet/in.h>
> #include<linux/types.h>
> #include<string.h>
>
> #ifndef CEPH_OSD_TMAP_SET
> #define CEPH_OSD_TMAP_HDR 'h'
> #define CEPH_OSD_TMAP_SET 's'
> #define CEPH_OSD_TMAP_RM  'r'
> #endif
>
> #define LIBRADOS_VER_MAJOR 0
> #define LIBRADOS_VER_MINOR 25
> #define LIBRADOS_VER_EXTRA 0
>
> #define LIBRADOS_VERSION(maj, min, extra) ((maj<<  16) + (min<<  8) + extra)
>
> #define LIBRADOS_VERSION_CODE LIBRADOS_VERSION(LIBRADOS_VER_MAJOR,
> LIBRADOS_VER_MINOR, LIBRADOS_VER_EXTRA)
>
> #define LIBRADOS_SUPPORTS_WATCH 1
>
> typedef void *rados_t;
> typedef void *rados_pool_t;
> typedef void *rados_list_ctx_t;
> typedef uint64_t rados_snap_t;
>
> struct rados_pool_stat_t {
>    uint64_t num_bytes;    // in bytes
>    uint64_t num_kb;       // in KB
>    uint64_t num_objects;
>    uint64_t num_object_clones;
>    uint64_t num_object_copies;  // num_objects * num_replicas
>    uint64_t num_objects_missing_on_primary;
>    uint64_t num_objects_unfound;
>    uint64_t num_objects_degraded;
>    uint64_t num_rd, num_rd_kb,num_wr, num_wr_kb;
> };
>
> struct rados_statfs_t {
>    uint64_t kb, kb_used, kb_avail;
>    uint64_t num_objects;
> };
>
>
> void rados_version(int *major, int *minor, int *extra);
>
> /* initialization */
> int rados_create(rados_t *cluster, const char * const id);
>
> /* Connect to the cluster */
> int rados_connect(rados_t cluster);
>
> /* destroy the cluster instance */
> void rados_destroy(rados_t cluster);
>
> /* Config
>   *
>   * Functions for manipulating the Ceph configuration at runtime.
>   * After changing the Ceph configuration, you should call rados_conf_apply to
>   * ensure that the changes have been applied.
>   */
> int rados_conf_read_file(rados_t cluster, const char *path);
>
> /* Sets a configuration value from a string.
>   * Returns 0 on success, error code otherwise. */
> int rados_conf_set(rados_t cluster, const char *option, const char *value);
>
> /* Reopens the log file.
>   * You must do this after changing the logging configuration.
>   * It is also good practice to call this from your SIGHUP signal
> handler, so that users can send you
>   * a SIGHUP to reopen the log.
>   */
> void rados_reopen_log(rados_t cluster);
>
> /* Returns a configuration value as a string.
>   * If len is positive, that is the maximum number of bytes we'll write into the
>   * buffer. If len == -1, we'll call malloc() and set *buf.
>   * Returns 0 on success, error code otherwise. Returns ENAMETOOLONG if the
>   * buffer is too short. */
> int rados_conf_get(rados_t cluster, const char *option, char *buf, int len);
> int rados_conf_get_alloc(rados_t cluster, const char *option, char **buf);
>
> /* pools */
> int rados_pool_open(rados_t cluster, const char *name, rados_pool_t *pool);
> int rados_pool_close(rados_pool_t pool);
> int rados_pool_lookup(rados_t cluster, const char *name);
>
> int rados_pool_stat(rados_pool_t pool, struct rados_pool_stat_t *stats);
>
> void rados_snap_set_read(rados_pool_t pool, rados_snap_t snap);
> int rados_snap_set_write_context(rados_pool_t pool, rados_snap_t seq,
> rados_snap_t *snaps, int num_snaps);
>
> int rados_pool_create(rados_t cluster, const char *name);
> int rados_pool_create_with_auid(rados_t cluster, const char *name,
> uint64_t auid);
> int rados_pool_create_with_crush_rule(rados_t cluster, const char
> *name, __u8 crush_rule);
> int rados_pool_create_with_all(rados_t cluster, const char *name, uint64_t auid,
> 			       __u8 crush_rule);
> int rados_pool_delete(rados_pool_t pool);
> int rados_pool_set_auid(rados_pool_t pool, uint64_t auid);
>
> /* objects */
> int rados_objects_list_open(rados_pool_t pool, rados_list_ctx_t *ctx);
> int rados_objects_list_next(rados_list_ctx_t ctx, const char **entry);
> void rados_objects_list_close(rados_list_ctx_t ctx);
>
>
> /* snapshots */
> int rados_pool_snap_create(rados_pool_t pool, const char *snapname);
> int rados_pool_snap_remove(rados_pool_t pool, const char *snapname);
> int rados_pool_snap_rollback_object(rados_pool_t pool, const char *oid,
> 			  const char *snapname);
> int rados_pool_selfmanaged_snap_create(rados_pool_t pool, uint64_t *snapid);
> int rados_pool_selfmanaged_snap_remove(rados_pool_t pool, uint64_t snapid);
> int rados_pool_snap_list(rados_pool_t pool, rados_snap_t *snaps, int maxlen);
> int rados_pool_snap_lookup(rados_pool_t pool, const char *name,
> rados_snap_t *id);
> int rados_pool_snap_get_name(rados_pool_t pool, rados_snap_t id, char
> *name, int maxlen);
>
> /* sync io */
> uint64_t rados_get_last_version(rados_pool_t pool);
>
> int rados_write(rados_pool_t pool, const char *oid, off_t off, const
> char *buf, size_t len);
> int rados_write_full(rados_pool_t pool, const char *oid, off_t off,
> const char *buf, size_t len);
> int rados_read(rados_pool_t pool, const char *oid, off_t off, char
> *buf, size_t len);
> int rados_remove(rados_pool_t pool, const char *oid);
> int rados_trunc(rados_pool_t pool, const char *oid, size_t size);
>
> /* attrs */
> int rados_getxattr(rados_pool_t pool, const char *o, const char *name,
> char *buf, size_t len);
> int rados_setxattr(rados_pool_t pool, const char *o, const char *name,
> const char *buf, size_t len);
> int rados_rmxattr(rados_pool_t pool, const char *o, const char *name);
>
> /* misc */
> int rados_stat(rados_pool_t pool, const char *o, uint64_t *psize,
> time_t *pmtime);
> int rados_tmap_update(rados_pool_t pool, const char *o, const char
> *cmdbuf, size_t cmdbuflen);
> int rados_exec(rados_pool_t pool, const char *oid, const char *cls,
> const char *method,
> 	       const char *in_buf, size_t in_len, char *buf, size_t out_len);
>
> /* async io */
> typedef void *rados_completion_t;
> typedef void (*rados_callback_t)(rados_completion_t cb, void *arg);
>
> int rados_aio_create_completion(void *cb_arg, rados_callback_t
> cb_complete, rados_callback_t cb_safe,
> 				rados_completion_t *pc);
> int rados_aio_wait_for_complete(rados_completion_t c);
> int rados_aio_wait_for_safe(rados_completion_t c);
> int rados_aio_is_complete(rados_completion_t c);
> int rados_aio_is_safe(rados_completion_t c);
> int rados_aio_get_return_value(rados_completion_t c);
> uint64_t rados_aio_get_obj_ver(rados_completion_t c);
> void rados_aio_release(rados_completion_t c);
> int rados_aio_write(rados_pool_t pool, const char *oid,
> 		    off_t off, const char *buf, size_t len,
> 		    rados_completion_t completion);
> int rados_aio_write_full(rados_pool_t pool, const char *oid,
> 			 off_t off, const char *buf, size_t len,
> 			 rados_completion_t completion);
> int rados_aio_read(rados_pool_t pool, const char *oid,
> 		   off_t off, char *buf, size_t len,
> 		   rados_completion_t completion);
>
> /* watch/notify */
> typedef void (*rados_watchcb_t)(uint8_t opcode, uint64_t ver, void *arg);
> int rados_watch(rados_pool_t pool, const char *o, uint64_t ver,
> uint64_t *handle,
>                  rados_watchcb_t watchcb, void *arg);
> int rados_unwatch(rados_pool_t pool, const char *o, uint64_t handle);
> int rados_notify(rados_pool_t pool, const char *o, uint64_t ver);
>
> #ifdef __cplusplus
> }
> #endif
>
> #endif
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

Re: proposed C API for librados

[Colin McCabe]

Yeah, should add something like that. Maybe something like this:

int rados_pool_list(rados_t cluster, char ***pools)
void rados_pool_list_free(char **pools)

Also should rename
rados_snap_set_read -> rados_snap_set_read_context for consistency.

Colin


On Wed, Feb 23, 2011 at 10:38 PM, Hannu Valtonen <me@ormod.com> wrote:
> On 2/24/11 8:09 AM, Colin McCabe wrote:
> Hi,
>
> If you're having a stab at this, could you please add a librados C api for
> listing of pools at the same time. (it's available on the C++ side but would
> be great to have on the C side for Python bindings)
>
>
>> Hi all,
>>
>> We're trying to finalize the API for librados for the 0.25 release.
>> This is the C API we're looking at.
>>
>> cheers,
>> Colin
>>
>>
>> =================================================================
>> #ifndef CEPH_LIBRADOS_H
>> #define CEPH_LIBRADOS_H
>>
>> #ifdef __cplusplus
>> extern "C" {
>> #endif
>>
>> #include<netinet/in.h>
>> #include<linux/types.h>
>> #include<string.h>
>>
>> #ifndef CEPH_OSD_TMAP_SET
>> #define CEPH_OSD_TMAP_HDR 'h'
>> #define CEPH_OSD_TMAP_SET 's'
>> #define CEPH_OSD_TMAP_RM  'r'
>> #endif
>>
>> #define LIBRADOS_VER_MAJOR 0
>> #define LIBRADOS_VER_MINOR 25
>> #define LIBRADOS_VER_EXTRA 0
>>
>> #define LIBRADOS_VERSION(maj, min, extra) ((maj<<  16) + (min<<  8) +
>> extra)
>>
>> #define LIBRADOS_VERSION_CODE LIBRADOS_VERSION(LIBRADOS_VER_MAJOR,
>> LIBRADOS_VER_MINOR, LIBRADOS_VER_EXTRA)
>>
>> #define LIBRADOS_SUPPORTS_WATCH 1
>>
>> typedef void *rados_t;
>> typedef void *rados_pool_t;
>> typedef void *rados_list_ctx_t;
>> typedef uint64_t rados_snap_t;
>>
>> struct rados_pool_stat_t {
>>   uint64_t num_bytes;    // in bytes
>>   uint64_t num_kb;       // in KB
>>   uint64_t num_objects;
>>   uint64_t num_object_clones;
>>   uint64_t num_object_copies;  // num_objects * num_replicas
>>   uint64_t num_objects_missing_on_primary;
>>   uint64_t num_objects_unfound;
>>   uint64_t num_objects_degraded;
>>   uint64_t num_rd, num_rd_kb,num_wr, num_wr_kb;
>> };
>>
>> struct rados_statfs_t {
>>   uint64_t kb, kb_used, kb_avail;
>>   uint64_t num_objects;
>> };
>>
>>
>> void rados_version(int *major, int *minor, int *extra);
>>
>> /* initialization */
>> int rados_create(rados_t *cluster, const char * const id);
>>
>> /* Connect to the cluster */
>> int rados_connect(rados_t cluster);
>>
>> /* destroy the cluster instance */
>> void rados_destroy(rados_t cluster);
>>
>> /* Config
>>  *
>>  * Functions for manipulating the Ceph configuration at runtime.
>>  * After changing the Ceph configuration, you should call rados_conf_apply
>> to
>>  * ensure that the changes have been applied.
>>  */
>> int rados_conf_read_file(rados_t cluster, const char *path);
>>
>> /* Sets a configuration value from a string.
>>  * Returns 0 on success, error code otherwise. */
>> int rados_conf_set(rados_t cluster, const char *option, const char
>> *value);
>>
>> /* Reopens the log file.
>>  * You must do this after changing the logging configuration.
>>  * It is also good practice to call this from your SIGHUP signal
>> handler, so that users can send you
>>  * a SIGHUP to reopen the log.
>>  */
>> void rados_reopen_log(rados_t cluster);
>>
>> /* Returns a configuration value as a string.
>>  * If len is positive, that is the maximum number of bytes we'll write
>> into the
>>  * buffer. If len == -1, we'll call malloc() and set *buf.
>>  * Returns 0 on success, error code otherwise. Returns ENAMETOOLONG if the
>>  * buffer is too short. */
>> int rados_conf_get(rados_t cluster, const char *option, char *buf, int
>> len);
>> int rados_conf_get_alloc(rados_t cluster, const char *option, char **buf);
>>
>> /* pools */
>> int rados_pool_open(rados_t cluster, const char *name, rados_pool_t
>> *pool);
>> int rados_pool_close(rados_pool_t pool);
>> int rados_pool_lookup(rados_t cluster, const char *name);
>>
>> int rados_pool_stat(rados_pool_t pool, struct rados_pool_stat_t *stats);
>>
>> void rados_snap_set_read(rados_pool_t pool, rados_snap_t snap);
>> int rados_snap_set_write_context(rados_pool_t pool, rados_snap_t seq,
>> rados_snap_t *snaps, int num_snaps);
>>
>> int rados_pool_create(rados_t cluster, const char *name);
>> int rados_pool_create_with_auid(rados_t cluster, const char *name,
>> uint64_t auid);
>> int rados_pool_create_with_crush_rule(rados_t cluster, const char
>> *name, __u8 crush_rule);
>> int rados_pool_create_with_all(rados_t cluster, const char *name, uint64_t
>> auid,
>>                               __u8 crush_rule);
>> int rados_pool_delete(rados_pool_t pool);
>> int rados_pool_set_auid(rados_pool_t pool, uint64_t auid);
>>
>> /* objects */
>> int rados_objects_list_open(rados_pool_t pool, rados_list_ctx_t *ctx);
>> int rados_objects_list_next(rados_list_ctx_t ctx, const char **entry);
>> void rados_objects_list_close(rados_list_ctx_t ctx);
>>
>>
>> /* snapshots */
>> int rados_pool_snap_create(rados_pool_t pool, const char *snapname);
>> int rados_pool_snap_remove(rados_pool_t pool, const char *snapname);
>> int rados_pool_snap_rollback_object(rados_pool_t pool, const char *oid,
>>                          const char *snapname);
>> int rados_pool_selfmanaged_snap_create(rados_pool_t pool, uint64_t
>> *snapid);
>> int rados_pool_selfmanaged_snap_remove(rados_pool_t pool, uint64_t
>> snapid);
>> int rados_pool_snap_list(rados_pool_t pool, rados_snap_t *snaps, int
>> maxlen);
>> int rados_pool_snap_lookup(rados_pool_t pool, const char *name,
>> rados_snap_t *id);
>> int rados_pool_snap_get_name(rados_pool_t pool, rados_snap_t id, char
>> *name, int maxlen);
>>
>> /* sync io */
>> uint64_t rados_get_last_version(rados_pool_t pool);
>>
>> int rados_write(rados_pool_t pool, const char *oid, off_t off, const
>> char *buf, size_t len);
>> int rados_write_full(rados_pool_t pool, const char *oid, off_t off,
>> const char *buf, size_t len);
>> int rados_read(rados_pool_t pool, const char *oid, off_t off, char
>> *buf, size_t len);
>> int rados_remove(rados_pool_t pool, const char *oid);
>> int rados_trunc(rados_pool_t pool, const char *oid, size_t size);
>>
>> /* attrs */
>> int rados_getxattr(rados_pool_t pool, const char *o, const char *name,
>> char *buf, size_t len);
>> int rados_setxattr(rados_pool_t pool, const char *o, const char *name,
>> const char *buf, size_t len);
>> int rados_rmxattr(rados_pool_t pool, const char *o, const char *name);
>>
>> /* misc */
>> int rados_stat(rados_pool_t pool, const char *o, uint64_t *psize,
>> time_t *pmtime);
>> int rados_tmap_update(rados_pool_t pool, const char *o, const char
>> *cmdbuf, size_t cmdbuflen);
>> int rados_exec(rados_pool_t pool, const char *oid, const char *cls,
>> const char *method,
>>               const char *in_buf, size_t in_len, char *buf, size_t
>> out_len);
>>
>> /* async io */
>> typedef void *rados_completion_t;
>> typedef void (*rados_callback_t)(rados_completion_t cb, void *arg);
>>
>> int rados_aio_create_completion(void *cb_arg, rados_callback_t
>> cb_complete, rados_callback_t cb_safe,
>>                                rados_completion_t *pc);
>> int rados_aio_wait_for_complete(rados_completion_t c);
>> int rados_aio_wait_for_safe(rados_completion_t c);
>> int rados_aio_is_complete(rados_completion_t c);
>> int rados_aio_is_safe(rados_completion_t c);
>> int rados_aio_get_return_value(rados_completion_t c);
>> uint64_t rados_aio_get_obj_ver(rados_completion_t c);
>> void rados_aio_release(rados_completion_t c);
>> int rados_aio_write(rados_pool_t pool, const char *oid,
>>                    off_t off, const char *buf, size_t len,
>>                    rados_completion_t completion);
>> int rados_aio_write_full(rados_pool_t pool, const char *oid,
>>                         off_t off, const char *buf, size_t len,
>>                         rados_completion_t completion);
>> int rados_aio_read(rados_pool_t pool, const char *oid,
>>                   off_t off, char *buf, size_t len,
>>                   rados_completion_t completion);
>>
>> /* watch/notify */
>> typedef void (*rados_watchcb_t)(uint8_t opcode, uint64_t ver, void *arg);
>> int rados_watch(rados_pool_t pool, const char *o, uint64_t ver,
>> uint64_t *handle,
>>                 rados_watchcb_t watchcb, void *arg);
>> int rados_unwatch(rados_pool_t pool, const char *o, uint64_t handle);
>> int rados_notify(rados_pool_t pool, const char *o, uint64_t ver);
>>
>> #ifdef __cplusplus
>> }
>> #endif
>>
>> #endif
>> --
>> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
>> the body of a message to majordomo@vger.kernel.org
>> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>>
>
>
--
To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: proposed C API for librados

[Wido den Hollander]

Hi,

On Wed, 2011-02-23 at 22:09 -0800, Colin McCabe wrote:

> #define LIBRADOS_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra)
> 
> #define LIBRADOS_VERSION_CODE LIBRADOS_VERSION(LIBRADOS_VER_MAJOR,
> LIBRADOS_VER_MINOR, LIBRADOS_VER_EXTRA)
> 
> #define LIBRADOS_SUPPORTS_WATCH 1

A few months ago I proposed a "librados-config" binary:
http://tracker.newdream.net/issues/334

$ librados-config --features
SUPPORTS_WATCH

This binary right now only supports --vernum and --version, but adding
"--features" would he useful imho.

> struct rados_pool_stat_t {
>   uint64_t num_bytes;    // in bytes
>   uint64_t num_kb;       // in KB

See my other post, why bytes and kb?

> /* Reopens the log file.
>  * You must do this after changing the logging configuration.
>  * It is also good practice to call this from your SIGHUP signal
> handler, so that users can send you
>  * a SIGHUP to reopen the log.
>  */
> void rados_reopen_log(rados_t cluster);
> 

What about syslog? Does librados support logging to syslog? Or only to
file?

In the future I foresee end-user using phprados, the python bindings or
other extensions/bindings which gives them direct RADOS access, but they
do not have full access to the system.

Would a buffer in librados be a extra option? A buffer which you could
read where you are able to find the last X log messages. We could have:

void rados_get_last_logmsg(rados_t cluster, char *buf);

buf would than be filled with the last log messages, very usefull if you
don't have full system access.

Other than that, the new API seems sane to me.

Wido


> /* Returns a configuration value as a string.
>  * If len is positive, that is the maximum number of bytes we'll write into the
>  * buffer. If len == -1, we'll call malloc() and set *buf.
>  * Returns 0 on success, error code otherwise. Returns ENAMETOOLONG if the
>  * buffer is too short. */
> int rados_conf_get(rados_t cluster, const char *option, char *buf, int len);
> int rados_conf_get_alloc(rados_t cluster, const char *option, char **buf);
> 
> /* pools */
> int rados_pool_open(rados_t cluster, const char *name, rados_pool_t *pool);
> int rados_pool_close(rados_pool_t pool);
> int rados_pool_lookup(rados_t cluster, const char *name);
> 
> int rados_pool_stat(rados_pool_t pool, struct rados_pool_stat_t *stats);
> 
> void rados_snap_set_read(rados_pool_t pool, rados_snap_t snap);
> int rados_snap_set_write_context(rados_pool_t pool, rados_snap_t seq,
> rados_snap_t *snaps, int num_snaps);
> 
> int rados_pool_create(rados_t cluster, const char *name);
> int rados_pool_create_with_auid(rados_t cluster, const char *name,
> uint64_t auid);
> int rados_pool_create_with_crush_rule(rados_t cluster, const char
> *name, __u8 crush_rule);
> int rados_pool_create_with_all(rados_t cluster, const char *name, uint64_t auid,
> 			       __u8 crush_rule);
> int rados_pool_delete(rados_pool_t pool);
> int rados_pool_set_auid(rados_pool_t pool, uint64_t auid);
> 
> /* objects */
> int rados_objects_list_open(rados_pool_t pool, rados_list_ctx_t *ctx);
> int rados_objects_list_next(rados_list_ctx_t ctx, const char **entry);
> void rados_objects_list_close(rados_list_ctx_t ctx);
> 
> 
> /* snapshots */
> int rados_pool_snap_create(rados_pool_t pool, const char *snapname);
> int rados_pool_snap_remove(rados_pool_t pool, const char *snapname);
> int rados_pool_snap_rollback_object(rados_pool_t pool, const char *oid,
> 			  const char *snapname);
> int rados_pool_selfmanaged_snap_create(rados_pool_t pool, uint64_t *snapid);
> int rados_pool_selfmanaged_snap_remove(rados_pool_t pool, uint64_t snapid);
> int rados_pool_snap_list(rados_pool_t pool, rados_snap_t *snaps, int maxlen);
> int rados_pool_snap_lookup(rados_pool_t pool, const char *name,
> rados_snap_t *id);
> int rados_pool_snap_get_name(rados_pool_t pool, rados_snap_t id, char
> *name, int maxlen);
> 
> /* sync io */
> uint64_t rados_get_last_version(rados_pool_t pool);
> 
> int rados_write(rados_pool_t pool, const char *oid, off_t off, const
> char *buf, size_t len);
> int rados_write_full(rados_pool_t pool, const char *oid, off_t off,
> const char *buf, size_t len);
> int rados_read(rados_pool_t pool, const char *oid, off_t off, char
> *buf, size_t len);
> int rados_remove(rados_pool_t pool, const char *oid);
> int rados_trunc(rados_pool_t pool, const char *oid, size_t size);
> 
> /* attrs */
> int rados_getxattr(rados_pool_t pool, const char *o, const char *name,
> char *buf, size_t len);
> int rados_setxattr(rados_pool_t pool, const char *o, const char *name,
> const char *buf, size_t len);
> int rados_rmxattr(rados_pool_t pool, const char *o, const char *name);
> 
> /* misc */
> int rados_stat(rados_pool_t pool, const char *o, uint64_t *psize,
> time_t *pmtime);
> int rados_tmap_update(rados_pool_t pool, const char *o, const char
> *cmdbuf, size_t cmdbuflen);
> int rados_exec(rados_pool_t pool, const char *oid, const char *cls,
> const char *method,
> 	       const char *in_buf, size_t in_len, char *buf, size_t out_len);
> 
> /* async io */
> typedef void *rados_completion_t;
> typedef void (*rados_callback_t)(rados_completion_t cb, void *arg);
> 
> int rados_aio_create_completion(void *cb_arg, rados_callback_t
> cb_complete, rados_callback_t cb_safe,
> 				rados_completion_t *pc);
> int rados_aio_wait_for_complete(rados_completion_t c);
> int rados_aio_wait_for_safe(rados_completion_t c);
> int rados_aio_is_complete(rados_completion_t c);
> int rados_aio_is_safe(rados_completion_t c);
> int rados_aio_get_return_value(rados_completion_t c);
> uint64_t rados_aio_get_obj_ver(rados_completion_t c);
> void rados_aio_release(rados_completion_t c);
> int rados_aio_write(rados_pool_t pool, const char *oid,
> 		    off_t off, const char *buf, size_t len,
> 		    rados_completion_t completion);
> int rados_aio_write_full(rados_pool_t pool, const char *oid,
> 			 off_t off, const char *buf, size_t len,
> 			 rados_completion_t completion);
> int rados_aio_read(rados_pool_t pool, const char *oid,
> 		   off_t off, char *buf, size_t len,
> 		   rados_completion_t completion);
> 
> /* watch/notify */
> typedef void (*rados_watchcb_t)(uint8_t opcode, uint64_t ver, void *arg);
> int rados_watch(rados_pool_t pool, const char *o, uint64_t ver,
> uint64_t *handle,
>                 rados_watchcb_t watchcb, void *arg);
> int rados_unwatch(rados_pool_t pool, const char *o, uint64_t handle);
> int rados_notify(rados_pool_t pool, const char *o, uint64_t ver);
> 
> #ifdef __cplusplus
> }
> #endif
> 
> #endif
> --
> To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: proposed C API for librados

[Sage Weil]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1763 bytes --]

On Wed, 23 Feb 2011, Colin McCabe wrote:
> Yeah, should add something like that. Maybe something like this:
> 
> int rados_pool_list(rados_t cluster, char ***pools)
> void rados_pool_list_free(char **pools)
>
> Also should rename
> rados_snap_set_read -> rados_snap_set_read_context for consistency.

Well, on the read side, it's not actually a context.  You just need to 
specify a snapid.  On the write side, the context tells the OSDs which 
snapshots to keep/cow when doing a write.  You can't write to a snapshot.  
I'm not sure the details are relevant to API users, but at the very least 
I don't think there is a clear symmetry between the read/write side to 
make the calls look consistent.  This way it's clear they're not...

Also,

> >> int rados_write(rados_pool_t pool, const char *oid, off_t off, const
> >> char *buf, size_t len);
> >> int rados_write_full(rados_pool_t pool, const char *oid, off_t off,
> >> const char *buf, size_t len);
> >> int rados_read(rados_pool_t pool, const char *oid, off_t off, char
> >> *buf, size_t len);

> >> int rados_aio_write(rados_pool_t pool, const char *oid,
> >>                    off_t off, const char *buf, size_t len,
> >>                    rados_completion_t completion);
> >> int rados_aio_write_full(rados_pool_t pool, const char *oid,
> >>                         off_t off, const char *buf, size_t len,
> >>                         rados_completion_t completion);
> >> int rados_aio_read(rados_pool_t pool, const char *oid,
> >>                   off_t off, char *buf, size_t len,
> >>                   rados_completion_t completion);

The argument order for these is weird... not quite sure what I was 
thinking.  Let's do whatever pread and pwrite do?

sage

Re: proposed C API for librados

[Colin McCabe]

On Thu, Feb 24, 2011 at 7:25 AM, Sage Weil <sage@newdream.net> wrote:
> On Wed, 23 Feb 2011, Colin McCabe wrote:
>> Yeah, should add something like that. Maybe something like this:
>>
>> int rados_pool_list(rados_t cluster, char ***pools)
>> void rados_pool_list_free(char **pools)
>>
>> Also should rename
>> rados_snap_set_read -> rados_snap_set_read_context for consistency.
>
> Well, on the read side, it's not actually a context.  You just need to
> specify a snapid.  On the write side, the context tells the OSDs which
> snapshots to keep/cow when doing a write.  You can't write to a snapshot.
> I'm not sure the details are relevant to API users, but at the very least
> I don't think there is a clear symmetry between the read/write side to
> make the calls look consistent.  This way it's clear they're not...
>

How about:
void rados_pool_snap_set_read(rados_pool_t pool, rados_snap_t snap);
int rados_pool_selfmanaged_snap_set_write_ctx(rados_pool_t pool,
rados_snap_t seq, rados_snap_t *snaps, int num_snaps);

The second one is getting long, but it ought to be clear that setting
the write context can only be done with selfmanaged snaps.

> ...
>
> The argument order for these is weird... not quite sure what I was
> thinking.  Let's do whatever pread and pwrite do?

pwrite has buf, count, offset, so we could go with that.

C.
--
To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: proposed C API for librados

[Colin McCabe]

Updated librados C API at

http://ceph.newdream.net/git/?p=ceph.git;a=blob;f=src/include/rados/librados.h;h=eda83d462d4763b9083efadd6890ae9b744b28ae;hb=librados_api

C.


On Thu, Feb 24, 2011 at 9:56 AM, Colin McCabe <cmccabe@alumni.cmu.edu> wrote:
> On Thu, Feb 24, 2011 at 7:25 AM, Sage Weil <sage@newdream.net> wrote:
>> On Wed, 23 Feb 2011, Colin McCabe wrote:
>>> Yeah, should add something like that. Maybe something like this:
>>>
>>> int rados_pool_list(rados_t cluster, char ***pools)
>>> void rados_pool_list_free(char **pools)
>>>
>>> Also should rename
>>> rados_snap_set_read -> rados_snap_set_read_context for consistency.
>>
>> Well, on the read side, it's not actually a context.  You just need to
>> specify a snapid.  On the write side, the context tells the OSDs which
>> snapshots to keep/cow when doing a write.  You can't write to a snapshot.
>> I'm not sure the details are relevant to API users, but at the very least
>> I don't think there is a clear symmetry between the read/write side to
>> make the calls look consistent.  This way it's clear they're not...
>>
>
> How about:
> void rados_pool_snap_set_read(rados_pool_t pool, rados_snap_t snap);
> int rados_pool_selfmanaged_snap_set_write_ctx(rados_pool_t pool,
> rados_snap_t seq, rados_snap_t *snaps, int num_snaps);
>
> The second one is getting long, but it ought to be clear that setting
> the write context can only be done with selfmanaged snaps.
>
>> ...
>>
>> The argument order for these is weird... not quite sure what I was
>> thinking.  Let's do whatever pread and pwrite do?
>
> pwrite has buf, count, offset, so we could go with that.
>
> C.
>
--
To unsubscribe from this list: send the line "unsubscribe ceph-devel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html