docs(ffi): comparison examples (#47)

docs: added ffi comparison examples
This commit is contained in:
əlemi 2024-10-14 14:13:35 +02:00 committed by GitHub
parent 85630d2667
commit cda0584b0e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 150 additions and 2 deletions

View file

@ -6,7 +6,7 @@ use tokio::sync::mpsc;
/// Poll all given buffer controllers and wait, returning the first one ready. /// Poll all given buffer controllers and wait, returning the first one ready.
/// ///
/// It will spawn tasks blocked on [`Controller::poll`] for each buffer controller. /// It will spawn tasks blocked on [`AsyncReceiver::poll`] for each buffer controller.
/// As soon as one finishes, its controller is returned and all other tasks are canceled. /// As soon as one finishes, its controller is returned and all other tasks are canceled.
/// ///
/// If a timeout is provided, the result may be `None` if it expires before any task is /// If a timeout is provided, the result may be `None` if it expires before any task is

View file

@ -2,12 +2,73 @@
//! `codemp` aims to be available as a library from as many programming languages as possible. //! `codemp` aims to be available as a library from as many programming languages as possible.
//! To achieve this, we rely on Foreign Function Interface. //! To achieve this, we rely on Foreign Function Interface.
//! //!
//! ```no_run
//! # async {
//! use codemp::api::controller::{AsyncReceiver, AsyncSender}; // needed for send/recv trait methods
//!
//! // connect first, api.code.mp is managed by hexed.technology
//! let client = codemp::Client::connect(codemp::api::Config::new(
//! "mail@example.net", "dont-use-this-password"
//! )).await?;
//!
//! // create and join a workspace
//! client.create_workspace("some-workspace").await?;
//! let workspace = client.join_workspace("some-workspace").await?;
//!
//! // create a new buffer in this workspace and attach to it
//! workspace.create("/my/file.txt").await?;
//! let buffer = workspace.attach("/my/file.txt").await?;
//!
//! // write `hello!` at the beginning of this buffer
//! buffer.send(codemp::api::TextChange {
//! start: 0, end: 0,
//! content: "hello!".to_string(),
//! })?;
//!
//! // wait for cursor movements
//! loop {
//! let event = workspace.cursor().recv().await?;
//! println!("user {} moved on buffer {}", event.user, event.sel.buffer);
//! }
//! # Ok::<(),Box<dyn std::error::Error>>(())
//! # };
//! ```
//!
//! ## JavaScript //! ## JavaScript
//! Our JavaScript glue is built with [`napi`](https://napi.rs). //! Our JavaScript glue is built with [`napi`](https://napi.rs).
//! //!
//! All async operations are handled on a separate tokio runtime, automatically managed by `napi`. //! All async operations are handled on a separate tokio runtime, automatically managed by `napi`.
//! Callbacks are safely scheduled to be called on the main loop thread. //! Callbacks are safely scheduled to be called on the main loop thread.
//! //!
//! ```js
//! import * as codemp from 'codemp';
//!
//! // connect first, api.code.mp is managed by hexed.technology
//! let client = await codemp.connect({
//! username: "mail@example.net", password: "dont-use-this-password"
//! });
//!
//! // create and join a workspace
//! await client.create_workspace("some-workspace");
//! let workspace = await client.join_workspace("some-workspace");
//!
//! // create a new buffer in this workspace and attach to it
//! await workspace.create("/my/file.txt");
//! let buffer = await workspace.attach("/my/file.txt");
//!
//! // write `hello!` at the beginning of this buffer
//! await buffer.send({
//! start: 0, end: 0,
//! content: "hello!",
//! });
//!
//! // wait for cursor movements
//! while (true) {
//! let event = await workspace.cursor().recv();
//! console.log(`user ${event.user} moved on buffer ${event.buffer}`);
//! }
//! ```
//!
//! ## Python //! ## Python
//! Our Python glue is built with [`PyO3`](https://pyo3.rs). //! Our Python glue is built with [`PyO3`](https://pyo3.rs).
//! //!
@ -15,6 +76,34 @@
//! value. The `Future` itself is run on a `tokio` runtime in a dedicated thread, which must be //! value. The `Future` itself is run on a `tokio` runtime in a dedicated thread, which must be
//! stared with `codemp.init()` before doing any async operations. //! stared with `codemp.init()` before doing any async operations.
//! //!
//! ```py
//! import codemp
//!
//! # connect first, api.code.mp is managed by hexed.technology
//! config = codemp.get_default_config()
//! config.username = "mail@example.net"
//! config.password = "dont-use-this-password"
//! client = codemp.connect(config).wait()
//!
//! # create and join a workspace
//! client.create_workspace("some-workspace").wait()
//! workspace = client.join_workspace("some-workspace").wait()
//!
//! # create a new buffer in this workspace and attach to it
//! workspace.create("/my/file.txt").wait()
//! buffer = workspace.attach("/my/file.txt").wait()
//!
//! # write `hello!` at the beginning of this buffer
//! buffer.send(
//! 0, 0, "hello!"
//! ).wait()
//!
//! # wait for cursor movements
//! while true:
//! event = workspace.cursor().recv().wait()
//! print(f"user {event.user} moved on buffer {event.buffer}")
//! ```
//!
//! ## Lua //! ## Lua
//! Our Lua glue is built with [`mlua`](https://github.com/mlua-rs/mlua). //! Our Lua glue is built with [`mlua`](https://github.com/mlua-rs/mlua).
//! //!
@ -33,6 +122,35 @@
//! We provide pre-built binaries at [codemp.dev/releases/lua](https://codemp.dev/releases/lua/). //! We provide pre-built binaries at [codemp.dev/releases/lua](https://codemp.dev/releases/lua/).
//! **Please do not rely on this link, as our built binaries will likely move somewhere else soon!**. //! **Please do not rely on this link, as our built binaries will likely move somewhere else soon!**.
//! //!
//! ```lua
//! CODEMP = require('codemp')
//!
//! -- connect first, api.code.mp is managed by hexed.technology
//! local client = CODEMP.connect({
//! username = "mail@example.net", password = "dont-use-this-password"
//! }):await()
//!
//! -- create and join a workspace
//! client:create_workspace("my-workspace"):await()
//! local workspace = client:join_workspace("my-workspace"):await()
//!
//! -- create a new buffer in this workspace and attach to it
//! workspace:create_buffer("/my/file.txt"):await()
//! local buffer = workspace:attach_buffer("/my/file.txt"):await()
//!
//! -- write `hello!` at the beginning of this buffer
//! buffer:send({
//! start = 0, finish = 0,
//! content = "hello!"
//! }):await()
//!
//! -- wait for cursor movements
//! while true do
//! local event = workspace.cursor:recv():await()
//! print("user " .. event.user .. " moved on buffer " .. event.buffer)
//! end
//! ```
//!
//! ## Java //! ## Java
//! Our Java glue is built with [`jni`](https://github.com/jni-rs/jni-rs). //! Our Java glue is built with [`jni`](https://github.com/jni-rs/jni-rs).
//! //!
@ -42,6 +160,34 @@
//! Exceptions coming from the native side have generally been made checked to imitate Rust's philosophy with `Result`. //! Exceptions coming from the native side have generally been made checked to imitate Rust's philosophy with `Result`.
//! `JNIException`s are however unchecked: there is nothing you can do to recover from them, as they usually represent a severe error in the glue code. If they arise, it's probably a bug. //! `JNIException`s are however unchecked: there is nothing you can do to recover from them, as they usually represent a severe error in the glue code. If they arise, it's probably a bug.
//! //!
//! ```java
//! import mp.code.*;
//!
//! // connect first, api.code.mp is managed by hexed.technology
//! Client client = Client.connect(
//! new data.Config("mail@example.net", "dont-use-this-password")
//! );
//!
//! // create and join a workspace
//! client.createWorkspace("some-workspace");
//! Workspace workspace = client.joinWorkspace("some-workspace");
//!
//! // create a new buffer in this workspace and attach to it
//! workspace.createBuffer("/my/file.txt");
//! BufferController buffer = workspace.attachToBuffer("/my/file.txt");
//!
//! // write `hello!` at the beginning of this buffer
//! buffer.send(new data.TextChange(
//! 0, 0, "hello!",
//! java.util.OptionalLong.empty() // optional, used for error detection
//! ));
//!
//! // wait for cursor movements
//! while (true) {
//! data.Cursor event = workspace.getCursor().recv();
//! System.out.printf("user %s moved on buffer %s\n", event.user, event.buffer);
//! }
//! ```
#![allow(clippy::unit_arg)] #![allow(clippy::unit_arg)]

View file

@ -88,8 +88,10 @@
//! * `python` //! * `python`
//! //!
//! For some of these, ready-to-use packages are available in various registries: //! For some of these, ready-to-use packages are available in various registries:
//! * [PyPI (python)](https://pypi.org/project/codemp)
//! * [npm (javascript)](https://www.npmjs.com/package/codemp) //! * [npm (javascript)](https://www.npmjs.com/package/codemp)
//! * [PyPI (python)](https://pypi.org/project/codemp)
//! * [Maven Central (java)](https://central.sonatype.com/artifact/mp.code/codemp)
//! * [LuaRocks (lua)](https://luarocks.org/modules/alemi/codemp)
//! //!
#![doc(html_logo_url = "https://code.mp/static/logo-round.png")] #![doc(html_logo_url = "https://code.mp/static/logo-round.png")]
#![doc(html_favicon_url = "https://code.mp/static/favicon.ico")] #![doc(html_favicon_url = "https://code.mp/static/favicon.ico")]