Add example of the blocking API

examples/async_api.c

@@ -0,0 +1,63 @@
+#include <stddef.h>
+#include <Toasty.h>
+
+int main(void)
+{
+    ToastyString remote_addr = TOASTY_STR("127.0.0.1");
+    uint16_t     remote_port = 8080;
+
+    Toasty *toasty = toasty_connect(remote_addr, remote_port);
+    if (toasty == NULL) {
+        printf("Couldn't connect to metadata server");
+        return -1;
+    }
+
+    ToastyString path_1 = TOASTY_STR("/first_file");
+    ToastyString path_2 = TOASTY_STR("/second_file");
+
+    char msg_1[] = "This is file 1";
+    char msg_2[] = "This is file 2";
+
+    // Begin creation operation. This does not block.
+    ToastyHandle create_handle_1 = toasty_begin_create_file(toasty, path_1, 1024);
+    if (create_handle_1 == TOASTY_INVALID) {
+        printf("Couldn't create file 1");
+        return -1;
+    }
+
+    // This doesn't block either.
+    ToastyHandle create_handle_2 = toasty_begin_create_file(toasty, path_2, 1024);
+    if (create_handle_2 == TOASTY_INVALID) {
+        printf("Couldn't create file 2");
+        return -1;
+    }
+
+    // Now block execution by overlapping the waiting
+    // times for both file creations.
+
+    ToastyResult result;
+    int ret = toasty_wait_result(toasty, create_handle_1, &result, -1);
+    if (ret < 0) {
+        printf("Couldn't wait for completion\n");
+        return -1;
+    }
+    if (result.type != TOASTY_RESULT_CREATE_SUCCESS) {
+        printf("Couldn't create file 1\n");
+        return -1;
+    }
+
+    ret = toasty_wait_result(toasty, create_handle_2, &result, -1);
+    if (ret < 0) {
+        printf("Couldn't wait for completion\n");
+        return -1;
+    }
+    if (result.type != TOASTY_RESULT_CREATE_SUCCESS) {
+        printf("Couldn't create file 2\n");
+        return -1;
+    }
+
+    printf("All files were created!\n");
+
+    toastyfs_disconnect(tfs);
+    return 0;
+}

examples/blocking_api.c

@@ -0,0 +1,34 @@
+#include <stddef.h>
+#include <Toasty.h>
+
+int main(void)
+{
+    ToastyString remote_addr = TOASTY_STR("127.0.0.1");
+    uint16_t     remote_port = 8080;
+
+    Toasty *toasty = toasty_connect(remote_addr, remote_port);
+    if (toasty == NULL) {
+        printf("Couldn't connect to metadata server");
+        return -1;
+    }
+
+    ToastyString path = TOASTY_STR("/first_file");
+
+    int ret = toasty_create_file(toasty, path, 1024);
+    if (ret < 0) {
+        printf("Couldn't create file\n");
+        toasty_disconnect(toasty);
+        return -1;
+    }
+
+    char data[] = "Hello, world!";
+    ret = toasty_write(toasty, path, 0, data, sizeof(data)-1);
+    if (ret < 0) {
+        printf("Couldn't write to file\n");
+        toasty_disconnect(toasty);
+        return -1;
+    }
+
+    toastyfs_disconnect(tfs);
+    return 0;
+}

examples/main.c

@@ -1,39 +0,0 @@
-#include <stddef.h>
-#include <ToastyFS.h>
-
-int main(void)
-{
-    ToastyFS *tfs = toastyfs_init("127.0.0.1", 8080);
-    if (tfs == NULL)
-        return -1;
-
-    if (toastyfs_submit_create(tfs, "/my_file_1", -1, false, 1024) < 0) {
-        toastyfs_free(tfs);
-        return -1;
-    }
-
-    if (toastyfs_submit_create(tfs, "/my_file_2", -1, false, 1024) < 0) {
-        toastyfs_free(tfs);
-        return -1;
-    }
-
-    char buff_1[] = "This is file 1";
-    if (toastyfs_submit_write(tfs, "/my_file_1", -1, 0, buff_1, sizeof(buff_1)-1) < 0) {
-        toastyfs_free(tfs);
-        return -1;
-    }
-
-    char buff_2[] = "This is file 2";
-    if (toastyfs_submit_write(tfs, "/my_file_1", -1, 0, buff_2, sizeof(buff_2)-1) < 0) {
-        toastyfs_free(tfs);
-        return -1;
-    }
-
-    for (int i = 0; i < 4; i++) {
-        ToastyFS_Result result;
-        toastyfs_wait(tfs, -1, &result, -1);
-    }
-
-    toastyfs_free(tfs);
-    return 0;
-}

inc/ToastyFS.h

@@ -7,7 +7,7 @@
 #include <stdint.h>
 #include <stdbool.h>
 
-// Get definition of "struct pollfd"
+// Get the definition of "struct pollfd"
 #ifdef _WIN32
 #include <winsock2.h>
 #else
@@ -67,10 +67,10 @@ typedef struct {
 // 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);
+Toasty *toasty_connect(ToastyString addr, uint16_t port);
 
 // Release all resources associated to this client
-void toasty_free(Toasty *tfs);
+void toasty_disconnect(Toasty *tfs);
 
 //////////////////////////////////////////////////////////////////////////////////
 // BLOCKING API
@@ -83,7 +83,8 @@ 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);
+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.
@@ -94,7 +95,8 @@ int toasty_delete(Toasty *tfs, ToastyString path);
 // 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);
+int toasty_list(Toasty *tfs, ToastyString path,
+    ToastyListing *listing);
 
 // Frees a listing created by "toasty_list".
 void toasty_free_listing(ToastyListing *listing);
@@ -102,12 +104,14 @@ 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);
+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);
+int toasty_write(Toasty *tfs, ToastyString path, int off,
+    void *src, int len);
 
 //////////////////////////////////////////////////////////////////////////////////
 // ASYNCHRONOUS API
@@ -119,7 +123,8 @@ 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);
+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
@@ -132,12 +137,14 @@ 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);
+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);
+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.
@@ -148,14 +155,16 @@ ToastyHandle toasty_begin_write(Toasty *tfs, ToastyString path, int off, void *s
 // 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);
+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);
+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".
@@ -167,7 +176,8 @@ void toasty_free_result(ToastyResult *result);
 
 // 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);
+int toasty_process_events(Toasty *tfs, void **contexts,
+    struct pollfd *polled, int num_polled);
 
 //////////////////////////////////////////////////////////////////////////////////
 // THE END