Crate tros

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.

Modules

error

transport

Structs

TokioExecutor

TokioExecutorBuilder

Builder for TokioExecutor.

Enums

TokioExecutorBuilderError

Error type for TokioExecutorBuilder