extracted yffi-impl

y-crdt · dileping · Jun 5, 2024 · Jul 11, 2024 · Jul 11, 2024 · Jul 18, 2024
commit cdd16c90cc1121e27950ec2915b2d330cf1f1143
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/yffi-impl/Cargo.toml b/yffi-impl/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "yffi-impl"
+version = "0.19.1"
+authors = ["Kevin Jahns <kevin.jahns@protonmail.com>", "Bartosz Sypytkowski <b.sypytkowski@gmail.com>"]
+keywords = ["crdt", "c-ffi", "yrs"]
+edition = "2018"
+license = "MIT"
+description = "Bindings for the Yrs native C foreign function interface"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+yrs = { path = "../yrs", version = "0.19.1", features = ["weak"] }
diff --git a/yffi-impl/README.md b/yffi-impl/README.md
@@ -0,0 +1,67 @@
+# Yrs C foreign function interface implementation
+
+The actual implementation of `yffi`.  It was separated from the `yffi` crate to make it an `rlib`. Acheiving the same without separation would require renaming `yffi`s exporting library (`yrs`) to avoid naming collision with the actual `yrs` crate.
+
+This project is a wrapper around [Yrs](../yrs/README.md) and targets native interop with possible host languages.
+
+It's a library used on collaborative document editing using Conflict-free Replicated Data Types.
+This enables to provide a shared document editing experience on a client devices without explicit requirement for hosting a single server - CRDTs can resolve potential update conflicts on their own with no central authority - as well as provide first-class offline editing capabilities, where document replicas are modified without having connection to each other, and then synchronize automatically once such connection is enabled.
+
+## [Documentation](https://docs.rs/yffi/0.9.3/yrs/)
+
+It's also possible to read it straight from a generated [C header file](https://github.com/y-crdt/y-crdt/blob/main/tests-ffi/include/libyrs.h).
+
+## Example
+
+```c
+#include <stdio.h>
+#include "libyrs.h"
+
+int main(void) {
+    YDoc* doc = ydoc_new();
+    YText* txt = ytext(doc, "name");
+    YTransaction* txn = ydoc_write_transaction(doc);
+
+    // append text to our collaborative document with no attributes
+    ytext_insert(txt, txn, 0, "hello world", NULL);
+
+    // simulate update with remote peer
+    YDoc* remote_doc = ydoc_new();
+    YText* remote_txt = ytext(remote_doc, "name");
+    YTransaction* remote_txn = ydoc_write_transaction(remote_doc);
+
+    // in order to exchange data with other documents
+    // we first need to create a state vector
+    int sv_length = 0;
+    unsigned char* remote_sv = ytransaction_state_vector_v1(remote_txn, &sv_length);
+
+    // now compute a differential update based on remote document's state vector
+    int update_length = 0;
+    unsigned char* update = ytransaction_state_diff_v1(txn, remote_sv, sv_length, &update_length);
+
+    // release resources no longer in use in the rest of the example
+    ybinary_destroy(remote_sv, sv_length);
+    ytransaction_commit(txn);
+    ydoc_destroy(doc);
+
+    // both update and state vector are serializable, we can pass them over the wire
+    // now apply update to a remote document
+    int err_code = ytransaction_apply(remote_txn, update, update_length);
+    if (0 != err_code) {
+        // error occurred when trying to apply an update
+        exit(err_code);
+    }
+    ybinary_destroy(update, update_length);
+
+    // retrieve string from remote peer YText instance
+    char* str = ytext_string(remote_txt, remote_txn);
+    printf("%s", str);
+
+    // release remaining resources
+    ystring_destroy(str);
+    ytransaction_commit(remote_txn);
+    ydoc_destroy(remote_doc);
+
+    return 0;
+}
+```