[sheepdog] [discuss v2] Design of Libsheepdog

[Kai Zhang]

Hi all,

Sorry for the delayed mail.

Here is the 2nd version of the design doc. It adopts many suggestions on the first version.
It also includes the design of asynchronous requests.

Please feel free to raise your suggestions.


Thanks,
Kyle


Design of Libsheepdog

Table of Contents

1. Original Intention
2. APIs
3. Asynchronous requests
1 Original Intention

Libsheepdog has been discussed for a long time. And it's time to introduce it to sheepdog project.

Libsheepdog provides the ability of operating vdi and vdi snapshot. It will be used by other systems which are built on top of sheepdog or use sheepdog as a sub-module.

2 APIs

typedef void *sd_t;
typedef struct sd_inode *sd_vdi_t;
struct sd_list_iter {
	void *opaqe;
	bool (*has_next)(void);
	union {
		char *(*next_string)(void);
		sd_vdi_t *(*next_snapshot)(void);
	}
	void (*destory)(void);
};

typedef void (sd_callback_fn)(struct const sd_t sd, int result, void *data);

/* connection */
int sd_init(char *addr, const sd_t *sd);
int sd_init_unix(char *path, const sd_t *sd);
int sd_ainit(char *addr, const sd_t *sd);
int sd_ainit_unix(char *path, const sd_t *sd);
int sd_close(sd_t *sd);

/* vdi */
int sd_vdi_create(sd_t sd, const char *name, size_t size, int copies,
		  bool prealloc, const sd_vdi_t *vdi);
int sd_vdi_clone(sd_t sd, const sd_vdi_t src_vdi, const char *dst_name,
		 const char *tag, int idx, int copies, const sd_vdi_t *dst_vdi);
int sd_vdi_open(sd_t sd, const char *name, const sd_vdi_t *vdi);
int sd_vdi_close(const sd_vdi_t *vdi);
int sd_vdi_read(sd_t sd, const sd_vdi_t vdi, void *data, size_t size,
		off_t offset);
int sd_vdi_aread(sd_t sd, const sd_vdi_t vdi, void *data, size_t size,
		 off_t offset, sd_callback_fn *fn, void *data,);
int sd_vdi_write(sd_t sd, sd_vdi_t vdi, void *data, size_t size,
		 off_t offset, int flag);
int sd_vdi_awrite(sd_t sd, sd_vdi_t vdi, void *data, size_t size, off_t offset,
		  int flag, sd_callback_fn *fn, void *data);
int sd_vdi_flush(sd_t sd, const sd_vdi_t vdi);
int sd_vdi_discard(sd_t sd, const sd_vdi_t vdi, off_t offset, size_t len);
int sd_vdi_resize(sd_t sd, const sd_vdi_t vdi, size_t size);
int sd_vdi_delete(sd_t sd, const char *name);
int sd_vdi_setattr(sd_t sd, const char *name, const char *key, void *value,
		   size_t value_len);
int sd_vdi_getattr(sd_t sd, const char *name, const char *key, void *value,
		   size_t value_len);
int sd_vdi_delattr(sd_t sd, const char *name, const char *key);
int sd_vdi_list(sd_t sd, sd_list_iter *iter);

/* snapshot */
int sd_snapshot_create(sd_t sd, const sd_vdi_t vdi, const char *tag,
		       const sd_vdi_t snap_vdi);
int sd_snapshot_open(sd_t sd, const char *name, const char *tag, int idx,
		     const sd_vdi_t *snap_vdi);
int sd_snapshot_rollback(sd_t sd, const sd_vdi_t vdi);
int sd_snapshot_read(sd_t sd, const sd_vdi_t vdi, void *data, size_t size,
		     off_t offset);
int sd_snapshot_aread(sd_t sd, const sd_vdi_t vdi, void *data, size_t size,
		      off_t offset, sd_callback_fn *fn, void *data);
int sd_snapshot_list(sd_t sd, const char *name, sd_list_iter *iter);

/* defined in other files */
int sd_libev_attach(EV_P_ sd_t sd);
int sd_libevent_attach(sd_t sd, struct event_base *base);
int sd_libuv_attach(sd_t sd, uv_loop_t *loop);
3 Asynchronous requests

Libsheepdog supports asynchronous requests such as sd_vdi_aread(), sd_vdi_awrite(). Libsheepdog implements asynchronous requests by asynchronous event library which is provided by user. For example, user can call sd_libev_attach to ask libsheepdog to use libev as event library.

Here are some advantages of this way:

remove dependencies of any event library, user can choose whichever they want.
better support of multi-platform than pthread
simple
This way is inspired from "hiredis" which is a client library of redis.

To avoid of exhausting memory, we have to add a limitation on buffer size used by libsheepdog. When it reachs the limitation, asynchronous request will return an error code which indicates "not enough memory". At this time, user should manually call a method to enlarge the buffer or try again later. (This method is not included in the first version of implementation.)

Author: Zhang Kai
Created: 2013-07-23 Tue 15:03
Emacs 24.1.1 (Org mode 8.0.2)
Validate XHTML 1.0
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.wpkg.org/pipermail/sheepdog/attachments/20130723/2ac49ecb/attachment-0003.html>