during 0.1.0

dlang wrapper around linux io_uring API


To use this package, run the following command in your project's root directory:

Manual usage
Put the following dependency into your project's dependences section:

during

Latest version Dub downloads Build status codecov license

Simple idiomatic dlang wrapper around linux io_uring(news) 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 (licensing issues, doesn't do anything we can't do directly with kernel syscalls, ...)
  • @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
  • @safe wrappers
  • up to date with not yet released Linux 5.5

Note:

  • not all operations are properly tested yet
  • Travis CI doesn't run on required linux kernels so it tests only builds (at least Linux 5.1 is needed)
  • same with the code coverage - as all tests fails when run
  • PR's are always welcome

Docs

View online on Github Pages

during uses adrdox to generate it's documentation. To build your own copy, run the following command from the root of the during repository:

path/to/adrdox/doc2 --genSearchIndex --genSource -o generated-docs source

Usage example

import during;
import std.range;

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
auto res = io
    .put(entry) // whole entry es 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);
assert(!io.empty);
assert(!io.front.user_data == 1);
io.popFront();

// 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); // operations has completed
assert(io.map!(c => c.user_data).equal(iota(0, 32)));

For more examples, see tests subfolder or the documentation.

How to use the library

Just add

depends "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 betterC tests run:

./betterc_ut.sh

Dub doesn't handle correctly packages with package.d and is too much hassle to ron betterC tests with it, so the script..

For a normal tests, just run:

dub test

See also Makefile for various targets.

Note: As we're using 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.

Authors:
  • Tomáš Chaloupka
Dependencies:
none
Versions:
0.3.0 2021-Nov-06
0.3.0-rc.3 2021-Oct-23
0.3.0-rc.2 2021-Aug-26
0.3.0-rc.1 2020-Sep-23
0.2.1 2020-Sep-06
Show all 10 versions
Download Stats:
  • 27 downloads today

  • 80 downloads this week

  • 310 downloads this month

  • 10910 downloads total

Score:
3.8
Short URL:
during.dub.pm