fd-queue 1.0.0-alpha.2

A library to support fd passing on Unix sockets.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# FD Queue

**FD Queue is a Rust abstraction for passing file descriptors between processes.**

[![CI](https://github.com/sbosnick/fd-queue/workflows/CI/badge.svg)](https://github.com/sbosnick/fd-queue/actions?query=workflow%3ACI)
---

fd-queue provides traits for enqueuing and dequeuing file descriptors and
implementations of those traits for different types of Unix sockets.
Specifically fd-queue provides a blocking implementation, a non-blocking
implementation base on [mio], and a non-blocking implementation based on
[tokio].

[mio]: https://crates.io/crates/mio
[tokio]: https://crates.io/crates/tokio

## Usage

Add this to your `Cargo.toml`

```toml
[dependencies]
fd-queue = {version = "1.0.0-alpha.1", features = ["net-fd"]}
```

This enables the blocking implementation of the traits for enqueuing and
dequeuing file descriptors. See below for the other features. You can then
use the library as follows:

```rust
use std::{
    fs::File,
    io::prelude::*,
    os::unix::io::FromRawFd,
};
use fd_queue::{EnqueueFd, DequeueFd, UnixStream};

let (mut sock1, mut sock2) = UnixStream::pair()?;

// sender side
let file: File = ...
sock1.enqueue(&file).expect("Can't enquque the file descriptor.");
sock1.write(b"a")?;
sock1.flush()?;

//receiver side
let mut buf = [0u8; 1];
sock2.read(&mut buf)?;
let fd = sock2.dequeue().expect("Can't dequeue the file descriptor.");
let file2 = unsafe { File::from_raw_fd(fd) };
```

## Features
Usage of the library with the default features will include only the basic
trait definitions `DequeueFd` and `EnqueueFd` together with their supporting
types. With the default features there will be no implementations of the basic
traits. To include implementations of the traits enable the following features:

| Feature  | Implementation | Additional Traits          |
----------------------------------------------------------
| net-fd   | blocking       | `Read`, `Write`            |
| mio-fd   | non-blocking   | `Read`, `Write`, `Evented` |
| tokio-fd | non-blocking   | `AsyncRead`, `AsyncWrite`  |

## Rust Version Requirements
The library will always support the Rust version that is two earlier
than the current stable version. The current Minimum Supported Rust
Version (MSRV) is 1.39.0. Any change to the MSRV will be treated as a
breaking change for Semantic Version purposes.

## Semantic Version and Release
This library follows [semantic versioning][semver], but without [Rust's
modification][rust-semver] to pre-1.0.0 minor version numbers. All
breaking changes will result in increasing the major version number.

This library also uses [Semantic Release][semrel] for its release process
which means that it will not have any pre-1.0.0 releases (for the reasons
described [here][no-pre-1.0.0]).

The first non-pre-release version of the library will be version 1.0.0. This
does not signal that the library is production ready or that we will attempt
to avoid breaking changes. It rather signals exactly what the [Semantic Versioning
Specification][semver] says it does: there won't be any backward incompatible
changes until version 2.0.0 (see [here][semver-8]).

For a signal of the maturity of the library see the next heading which will be
updated as the library matures.

[no-pre-1.0.0]: https://semantic-release.gitbook.io/semantic-release/support/faq#can-i-set-the-initial-release-version-of-my-package-to-0-0-1
[rust-semver]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field
[semrel]: https://semantic-release.gitbook.io/semantic-release/
[semver]: https://semver.org/
[semver-8]: https://semver.org/#spec-item-8

## Maturity
This library is an initial, experimental implementation that has not had any
use in production. You should expect breaking changes (with an appropriate change
in [semantic version][semver]) as the library matures.

## License

FD Queue is licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE-2.0](LICENSE-APACHE-2.0) or
   http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
   http://opensource.org/licenses/MIT)

at your option.

## Contribution

Please note that this project is released with a [Contributor Code of
Conduct][code-of-conduct].  By participating in this project you agree to abide
by its terms.

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in FD Queue by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

[code-of-conduct]: CODE_OF_CONDUCT.md