summaryrefslogtreecommitdiff
path: root/man/io_uring_register_ring_fd.3
blob: 144262fdca8f3b09208815fdfb0d7a4b09ebf2a0 (plain)
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
.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_register_ring_fd 3 "March 11, 2022" "liburing-2.2" "liburing Manual"
.SH NAME
io_uring_register_ring_fd   - register a ring file descriptor

.SH SYNOPSIS
.nf
.BR "#include <liburing.h>"
.PP
.BI "int io_uring_register_ring_fd(struct io_uring *" ring ");"

.SH DESCRIPTION
.PP
io_uring_register_ring_fd() registers the file descriptor of the ring.

Whenever
.BR io_uring_enter (2)
is called to submit request or wait for completions, the kernel must grab a
reference to the file descriptor. If the application using io_uring is threaded,
the file table is marked as shared, and the reference grab and put of the file
descriptor count is more expensive than it is for a non-threaded application.

Similarly to how io_uring allows registration of files, this allow registration
of the ring file descriptor itself. This reduces the overhead of the
.BR io_uring_enter (2)
system call.

If an application using liburing is threaded, then an application should call
this function to register the ring descriptor when a ring is set up. See NOTES
for restrictions when a ring is shared.

.SH NOTES
When the ring descriptor is registered, it is stored internally in the
.I struct io_uring
structure. For applications that share a ring between threads, for example
having one thread do submits and another reap events, then this optimization
cannot be used as each thread may have a different index for the registered
ring fd.
.SH RETURN VALUE
Returns 1 on success, indicating that one file descriptor was registered,
or
.B -errno
on error.
.SH SEE ALSO
.BR io_uring_unregister_ring_fd (3), io_uring_register_files (3)