From 58d2d7def319736ec71827debec6a4dff51b5eee Mon Sep 17 00:00:00 2001 From: Francesco Cozzuto Date: Sun, 16 Nov 2025 11:59:58 +0100 Subject: [PATCH] Polish API in ToastyFS.h --- inc/ToastyFS.h | 187 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 153 insertions(+), 34 deletions(-) diff --git a/inc/ToastyFS.h b/inc/ToastyFS.h index fa8b6d2..23f7a56 100644 --- a/inc/ToastyFS.h +++ b/inc/ToastyFS.h @@ -1,56 +1,175 @@ -#ifndef TOASTYFS_INCLUDED -#define TOASTYFS_INCLUDED +#ifndef TOASTY_INCLUDED +#define TOASTY_INCLUDED +////////////////////////////////////////////////////////////////////////////////// +// INCLUDES +////////////////////////////////////////////////////////////////////////////////// #include #include +// Get definition of "struct pollfd" #ifdef _WIN32 #include #else #include #endif -typedef struct ToastyFS ToastyFS; +////////////////////////////////////////////////////////////////////////////////// +// TYPES & UTILITIES +////////////////////////////////////////////////////////////////////////////////// + +typedef struct Toasty Toasty; + +// Helper type to avoid zero-terminated strings +typedef struct { + char *ptr; + int len; +} ToastyString; + +// Macro to convert string literals to ToastyStrings +#define TOASTY_STR(X) ((ToastyString) { (X), (int) sizeof(X)-1 }) + +// Handle representing a pending operation +typedef uint32_t ToastyHandle; + +// Invalid value for a ToastyHandle +#define TOASTY_INVALID ((ToastyHandle) 0) typedef struct { char name[128]; // TODO: Implement a proper name length bool is_dir; -} ToastyFS_Entity; - -typedef enum { - TOASTYFS_RESULT_EMPTY, - TOASTYFS_RESULT_CREATE_ERROR, - TOASTYFS_RESULT_CREATE_SUCCESS, - TOASTYFS_RESULT_DELETE_ERROR, - TOASTYFS_RESULT_DELETE_SUCCESS, - TOASTYFS_RESULT_LIST_ERROR, - TOASTYFS_RESULT_LIST_SUCCESS, - TOASTYFS_RESULT_READ_ERROR, - TOASTYFS_RESULT_READ_SUCCESS, - TOASTYFS_RESULT_WRITE_ERROR, - TOASTYFS_RESULT_WRITE_SUCCESS, -} ToastyFS_ResultType; +} ToastyListingEntry; typedef struct { + int count; + ToastyListingEntry *items; +} ToastyListing; - ToastyFS_ResultType type; +typedef enum { + TOASTY_RESULT_EMPTY, + TOASTY_RESULT_CREATE_ERROR, + TOASTY_RESULT_CREATE_SUCCESS, + TOASTY_RESULT_DELETE_ERROR, + TOASTY_RESULT_DELETE_SUCCESS, + TOASTY_RESULT_LIST_ERROR, + TOASTY_RESULT_LIST_SUCCESS, + TOASTY_RESULT_READ_ERROR, + TOASTY_RESULT_READ_SUCCESS, + TOASTY_RESULT_WRITE_ERROR, + TOASTY_RESULT_WRITE_SUCCESS, +} ToastyResultType; - int num_entities; - ToastyFS_Entity *entities; -} ToastyFS_Result; +typedef struct { + ToastyResultType type; + ToastyListing listing; +} ToastyResult; -ToastyFS *toastyfs_init(char *addr, uint16_t port); -void toastyfs_free(ToastyFS *tfs); -void toastyfs_wait(ToastyFS *tfs, int opidx, ToastyFS_Result *result, int timeout); +// Instanciate a ToastyFS client object. The "addr" and "port" +// arguments refer to the address and port of the cluster's +// metadata server. +Toasty *toasty_init(char *addr, uint16_t port); -bool toastyfs_isdone(ToastyFS *tfs, int opidx, ToastyFS_Result *result); -int toastyfs_process_events(ToastyFS *tfs, void **contexts, struct pollfd *polled, int num_polled); +// Release all resources associated to this client +void toasty_free(Toasty *tfs); -int toastyfs_submit_create (ToastyFS *tfs, char *path, int path_len, bool is_dir, unsigned int chunk_size); -int toastyfs_submit_delete (ToastyFS *tfs, char *path, int path_len); -int toastyfs_submit_list (ToastyFS *tfs, char *path, int path_len); -int toastyfs_submit_read (ToastyFS *tfs, char *path, int path_len, int off, void *dst, int len); -int toastyfs_submit_write (ToastyFS *tfs, char *path, int path_len, int off, void *src, int len); -void toastyfs_result_free(ToastyFS_Result *result); +////////////////////////////////////////////////////////////////////////////////// +// BLOCKING API +////////////////////////////////////////////////////////////////////////////////// -#endif // TOASTYFS_INCLUDED +// Creates a directory at the specified path. +// Returns 0 on success, -1 on error. +int toasty_create_dir(Toasty *tfs, ToastyString path); + +// Creates a file with the given chunk size at +// the specified path. Returns 0 on success, -1 +// on error. The chunk size can't be 0. +int toasty_create_file(Toasty *tfs, ToastyString path, unsigned int chunk_size); + +// Deletes a file or directory at the specified path. +// Returns 0 on success, -1 on error. +int toasty_delete(Toasty *tfs, ToastyString path); + +// Lists all files and directories within the given +// path. Returns 0 and fills up the listing argument +// on success, returns -1 on error. The listing is +// a dynamic array that needs to be freed using +// "toasy_free_listing". +int toasty_list(Toasty *tfs, ToastyString path, ToastyListing *listing); + +// Frees a listing created by "toasty_list". +void toasty_free_listing(ToastyListing *listing); + +// Reads "len" bytes at offset "off" from the file at +// the given path. Returns the number of bytes read on +// success, or -1 on error. +int toasty_read(Toasty *tfs, ToastyString path, int off, void *dst, int len); + +// Writes "len" bytes at offset "off" to the file at +// the given path. Returns the number of bytes written +// on success, or -1 on error. +int toasty_write(Toasty *tfs, ToastyString path, int off, void *src, int len); + +////////////////////////////////////////////////////////////////////////////////// +// ASYNCHRONOUS API +////////////////////////////////////////////////////////////////////////////////// + +// Begins a directory creation operation and returns +// a handle to it. On error, TOASTY_INVALID is returned. +ToastyHandle toasty_begin_create_dir(Toasty *tfs, ToastyString path); + +// Begins a file creation operation and returns a +// handle to it. On error, TOASTY_INVALID is returned. +ToastyHandle toasty_begin_create_file(Toasty *tfs, ToastyString path, unsigned int chunk_size); + +// Begins a file or directory deletion operation and +// returns a handle to it. On error, TOASTY_INVALID is +// returned. +ToastyHandle toasty_begin_delete(Toasty *tfs, ToastyString path); + +// Begins a directory listing operation and returns +// a handle to it. On error, TOASTY_INVALID is returned. +ToastyHandle toasty_begin_list(Toasty *tfs, ToastyString path); + +// Begins a read operation and returns a handle to it. +// On error, TOASTY_INVALID is returned. +ToastyHandle toasty_begin_read(Toasty *tfs, ToastyString path, int off, void *dst, int len); + +// Begins a write operation and returns a handle to it. +// On error, TOASTY_INVALID is returned. Note that the source +// buffer must be valid until the operation completes. +ToastyHandle toasty_begin_write(Toasty *tfs, ToastyString path, int off, void *src, int len); + +// If the operation specified by "handle" is complete, +// its result is stored in "result" and 0 is returned. +// If the operation is still in progress, 1 is returned. +// On error, -1 is returned. If the handle is TOASTY_INVALID, +// then the result of the first complete operation is +// returned. +// Note that if a result is returned, handles to that +// operation are invalidated. +// The "result" must be freed using "toasty_free_result". +int toasty_get_result(Toasty *tfs, ToastyHandle handle, ToastyResult *result); + +// Blocks execution until an operation is complete. This works +// like "toasty_get_result", except it waits for "timeout" milliseconds +// if the result isn't available. If "timeout" is -1, it waits +// indefinitely. +// The "result" must be freed using "toasty_free_result". +int toasty_wait_result(Toasty *tfs, ToastyHandle handle, ToastyResult *result, int timeout); + +// Frees resources of a "ToastyResult" previously initialized +// by "toasty_get_result" or "toasty_wait_result". +void toasty_free_result(ToastyResult *result); + +////////////////////////////////////////////////////////////////////////////////// +// OTHER +////////////////////////////////////////////////////////////////////////////////// + +// This is a hook for the simulation testing framework. +// You shouldn't need to use this. +int toasty_process_events(Toasty *tfs, void **contexts, struct pollfd *polled, int num_polled); + +////////////////////////////////////////////////////////////////////////////////// +// THE END +////////////////////////////////////////////////////////////////////////////////// +#endif // TOASTY_INCLUDED