Struct close_fds::FdIterBuilder [−][src]
pub struct FdIterBuilder { /* fields omitted */ }
Expand description
A “builder” to construct an FdIter
with custom parameters.
Warnings
TL;DR: Don’t use FdIter
/FdIterBuilder
in multithreaded programs unless you know what
you’re doing, and avoid opening/closing file descriptors while consuming an FdIter
.
-
File descriptors that are opened during iteration may or may not be included in the results (exact behavior is platform-specific and depends on several factors).
-
IMPORTANT: On some platforms, if other threads open file descriptors at very specific times during a call to
FdIter::next()
, that may result in other file descriptors being skipped. Use with caution. (If this is a problem for you, set.threadsafe(true)
, which avoids this issue). -
Closing file descriptors during iteration (in the same thread or in another thread) will not affect the iterator’s ability to list other open file descriptors (if it does, that is a bug). However, in most cases you should use
CloseFdsBuilder
to do this. -
Some of the file descriptors yielded by this iterator may be in active use by other sections of code. Be very careful about which operations you perform on them.
If your program is multi-threaded, this is especially true, since a file descriptor returned by this iterator may have been closed by the time your code tries to do something with it.
Implementations
Create a new builder.
minfd
specifies the number of the file descriptor at which iteration will begin.
Set whether the returned FdIter
is allowed to yield invalid file descriptors for
efficiency (default is false
).
If this flag is set, the caller is responsible for checking if the returned file descriptors are valid.
Proper usage
You should only use this flag if you immediately perform an operation on each file descriptor that implicitly checks if the file descriptor is valid.
Set whether the returned FdIter
needs to behave reliably in multithreaded programs
(default is false
).
If other threads open file descriptors at specific times, an FdIter
may skip over other
file descriptors. Setting .threadsafe(true)
prevents this, but may come at the cost of
significantly increased performance on some platforms (because the code which may behave
strangely in the presence of threads provides a potential performance improvement).
Currently, setting this flag will only affect performance on 1) OpenBSD and 2) FreeBSD
without an fdescfs
mounted on /dev/fd
.
Set whether returned FdIter
is allowed to look at special files for speedups (default is
true
).
On some systems, /dev/fd
and/or /proc/self/fd
provide an accurate view of the file
descriptors that the current process has open; if this flag is set to true
then those
may be examined as an optimization.
It may be desirable to set this to false
e.g. if chroot()
ing into an environment where
untrusted code may be able to replace /proc
or /dev
. However, on some platforms (such
as Linux<5.9 and macOS) setting this to false
may significantly decrease performance.