[sheepdog] [disscuss] Design of Libsheepdog

[Liu Yuan]

On Wed, Jun 26, 2013 at 10:51:26AM +0800, Kai Zhang wrote:
> Hi all
> 
> As we discussed in the last IRC meeting, I would like to propose an initial design
> of libsheepdog. 
> 
> It is just quite initial, to avoid of waisting much time on wrong things.
> 
> Please feel free to raise your suggestions.
> 
> (PS: the doc is in html format. if you stuck on it, I will send a plain text version)
> 
> Thanks,
> Kyle
> 
> 
> Design of Libsheepdog
> 
> Table of Contents
> 
> 1. Original Intention
> 2. APIs
> 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 string_iterator {
> 	void *opaqe;
> 	bool (*has_next)(void);
> 	char *(*next)(void);
> 	void (*destory)(void);
> };

maybe better named as sd_list_iter

> 
> /* connection */
> int sd_init(char *addr, 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,
> 		 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,
> 		size_t offset);
> int sd_vdi_write(sd_t sd, const sd_vdi_t vdi, void *data, size_t size,
> 		 size_t offset, bool writeback);
> 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_list(sd_t sd, string_iterator *si);
> 
> /* snapshot */
> int sd_vdi_snap_create(sd_t sd, const sd_vdi_t vdi, const char *tag,
> 		       const sd_vdi_t snap_vdi);
> int sd_vdi_snap_open(sd_t sd, const char *name, const char *tag, int idx,
> 		     const sd_vdi_t *snap_vdi);
> int sd_vdi_snap_rollback(sd_t sd, const sd_vdi_t vdi);
> int sd_vdi_snap_read(sd_t sd, const sd_vdi_t vdi, void *data, size_t size,
> 		     size_t offset);
> Here are some semantics behind them:
> 
> sd_t and sd_vdi_t are created and destroyed explicitly by calling the APIs, but user don't need to care about the memory
> current APIs are all blocking, and no additional thread in backgroud
> TODO:
> 
> asychronous APIs if needed

This is surely needed for best performance. But can be considered when blocking
API is implemeted.

Thanks,
Yuan