blob: 0e872bdd6b431963047a05a50047416fc8254b99 (
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
|
.\" 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. If an application shares this structure between threads, then this
optimization cannot be used as the threads may get different values for the
registered descriptor.
.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)
|
