Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tchaloupka/during
dlang io_uring wrapper
https://github.com/tchaloupka/during
Last synced: about 1 month ago
JSON representation
dlang io_uring wrapper
- Host: GitHub
- URL: https://github.com/tchaloupka/during
- Owner: tchaloupka
- License: bsl-1.0
- Created: 2019-11-30T23:37:31.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2023-09-27T21:13:42.000Z (about 1 year ago)
- Last Synced: 2024-05-22T14:33:42.755Z (7 months ago)
- Language: D
- Homepage: https://tchaloupka.github.io/during/during.html
- Size: 987 KB
- Stars: 29
- Watchers: 4
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-iouring - during
README
# during
[](https://code.dlang.org/packages/during)
[](http://code.dlang.org/packages/during)
[](https://github.com/tchaloupka/during/actions)
[](https://codecov.io/gh/tchaloupka/during)
[](https://github.com/tchaloupka/during/blob/master/LICENSE)
Simple idiomatic [dlang](https://dlang.org) wrapper around linux [io_uring](https://kernel.dk/io_uring.pdf)([news](https://kernel.dk/io_uring-whatsnew.pdf)) asynchronous API.
It's just a low level wrapper, doesn't try to do fancy higher level stuff, but attempts to provide building blocks for it.
Main features:
* doesn't use [liburing](https://git.kernel.dk/cgit/liburing/) (doesn't do anything we can't do directly with kernel syscalls in a more D idiomatic way)
* `@nogc`, `nothrow`, `betterC` are supported
* simple usage with provided API D interface
* range interface to submit and receive operations
* helper functions to prepare operations
* chainable function calls
* up to date with Linux 5.14
**Note:**
* not all operations are properly tested yet (from Kernel 5.4, 5.5, 5.6, 5.7, 5.8)
* PR's are always welcome
## Docs
[View online on Github Pages](https://tchaloupka.github.io/during/during.html)
`during` uses [adrdox](https://github.com/adamdruppe/adrdox) to generate it's documentation. To build your own
copy, run the following command from the root of the `during` repository:
```BASH
path/to/adrdox/doc2 --genSearchIndex --genSource -o generated-docs source
```
## Usage example
```D
import during;
import std.range : drop, iota;
import std.algorithm : copy, equal, map;
Uring io;
auto res = io.setup();
assert(res >= 0, "Error initializing IO");
SubmissionEntry entry;
entry.opcode = Operation.NOP;
entry.user_data = 1;
// custom operation to allow usage customization
struct MyOp { Operation opcode = Operation.NOP; ulong user_data; }
// chain operations
res = io
.put(entry) // whole entry as defined by io_uring
.put(MyOp(Operation.NOP, 2)) // custom op that would be filled over submission queue entry
.putWith!((ref SubmissionEntry e) // own function to directly fill entry in a queue
{
e.prepNop();
e.user_data = 42;
})
.submit(1); // submit operations and wait for at least 1 completed
assert(res == 3); // 3 operations were submitted to the submission queue
assert(!io.empty); // at least one operation has been completed
assert(io.front.user_data == 1);
io.popFront(); // drop it from the completion queue
// wait for and drop rest of the operations
io.wait(2);
io.drop(2);
// use range API to post some operations
iota(0, 16).map!(a => MyOp(Operation.NOP, a)).copy(io);
// submit them and wait for their completion
res = io.submit(16);
assert(res == 16);
assert(io.length == 16); // all operations has completed
assert(io.map!(c => c.user_data).equal(iota(0, 16)));
```
For more examples, see `tests` and `examples` subfolders or the documentation.
## How to use the library
Just add
```
dependency "during" version="~>0.1.0"
```
to your `dub.sdl` project file, or
```
"dependencies": {
"during: "~>0.1.0"
}
```
to your `dub.json` project file.
## Running tests
For a normal tests, just run:
```
dub test
```
See also `Makefile` for other targets.
**Note:** As we're using [silly](http://code.dlang.org/packages/silly) as a unittest runner, it runs tests in multiple threads by default.
This can be a problem as each `io_uring` consumes some pages from `memlock` limit (see `ulimit -l`).
To avoid that, add `-- -t 1` to the command to run it single threaded.
## Benchmark
See [echo_server](https://github.com/tchaloupka/during/tree/master/examples/echo_server) sample implementation.