# `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:

```rust
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](https://github.com/picodata/tarantool), which means we can give you some optimizations, congrats! 🥳

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

1. 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`  |

1. Install `tros` with the needed feature by adding it to `Cargo.toml`, for example: `tros = { version = "0.1.0", features = [ "picodata" ] }`

1. Use enabled transports in your code, for example:
   1. For picodata: `TokioExecutor::new(PicodataTransport::default()).exec(...)`;
   1. For vanilla: `TokioExecutor::new(VanillaTransport::default()).exec(...)`;

## Details

### Transports

Normally you should not choose transport yourself.
Just pick a suitable feature as described [above](#get-started) 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](https://github.com/picodata/tarantool). 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`.