4 releases

0.1.3 Apr 25, 2024
0.1.2 Mar 21, 2024
0.1.1 Jan 30, 2024
0.1.0 Jan 30, 2024

#276 in Asynchronous

Download history 5/week @ 2024-01-27 17/week @ 2024-02-17 37/week @ 2024-02-24 1/week @ 2024-03-02 6/week @ 2024-03-09 116/week @ 2024-03-16 16/week @ 2024-03-23 84/week @ 2024-03-30 146/week @ 2024-04-06 408/week @ 2024-04-13 555/week @ 2024-04-20 19/week @ 2024-04-27 139/week @ 2024-05-04 173/week @ 2024-05-11

928 downloads per month

BSD-2-Clause

21KB
292 lines

tros - your tros to tokio(...and others)

Introduction

Tros is an off line tarantool executor. It is your bridge from TX thread to ordinary external threads - namely, to the tokio runtime. To get a quick glimpse of what it offers, lets make an async HTTP request with it:

let text = TokioExecutor::new(PicodataTransport::default())
            .exec(async { reqwest::get("http://example.com").await?.text().await })
            .unwrap()
            .unwrap();
assert!(text.contains("Example Domain"))

Internally it would go through the following steps:

  1. Create tokio runtime if it doesn't exist yet;
  2. Start future execution on the runtime;
  3. Receive future's result through the underlying channel. Result awaiting scheme depends on the transport used.

Get started

  1. To get started, first understand what tarantool version you are using. You can do it via tarantool --version.

    1. If it says picodata somewhere, then you are using our fork, which means we can give you some optimizations, congrats! 🥳

    2. If it doesn't say picodata, then you are on vanilla tarantool.

  2. Then take a look at the table below to pick needed features and items:

    TT Version Cargo feature What it enables
    Picodata fork picodata PicodataTransport
    Vanilla vanilla VanillaTransport
  3. Install tros with the needed feature by adding it to Cargo.toml, for example: tros = { version = "0.1.0", features = [ "picodata" ] }

  4. Use enabled transports in your code, for example:

    1. For picodata: TokioExecutor::new(PicodataTransport::default()).exec(...);
    2. For vanilla: TokioExecutor::new(VanillaTransport::default()).exec(...);

Details

Transports

Normally you should not choose transport yourself. Just pick a suitable feature as described above and you are good to go with the automatically selected transport.

If you are indeed interested in the underlying transport details, take a look at transport comparison table:

Type Description Pros Cons
CBusTransport It uses CBus oneshot channel to receive job result. As it uses CBus channel, it is very efficient: it simply puts current fiber to sleep and, as a result, doesn't waste additional resources. For the moment of writing, it is only available in the picodata fork. There is an ongoing effort to push CBus patch to the upstream.
PollTransport It polls underlying channel with the configurable interval to receive job result. It is available in all modern tarantool versions. As it polls channel with some interval, it is not very efficient.

Examples

Examples are placed in example crate. To simplify their execution, each example is just tarantool test. To run and check examples, install tarantool-test binary and run make run-examples.

Dependencies

~10–17MB
~225K SLoC