Struct ListenerOptions 

pub struct ListenerOptions<'n> { /* private fields */ }

Server-side builder for local socket listeners, including Listener.

Implementations

impl ListenerOptions<'_>

Creation and ownership.

pub fn new() -> Self

Returns a default set of listener options.

impl<'n> ListenerOptions<'n>

Option setters.

pub fn name(self, name: Name<'n>) -> Self

Sets the name the server will listen on.

pub fn nonblocking(self, nonblocking: ListenerNonblockingMode) -> Self

Selects the nonblocking mode to be used by the listener.

The default value is Neither.

pub fn reclaim_name(self, reclaim_name: bool) -> Self

Sets whether name reclamation is to happen or not.

This is enabled by default.

pub fn try_overwrite(self, try_overwrite: bool) -> Self

Sets whether an attempt to handle AddrInUse errors by overwriting an existing listener (in the same manner as in name reclamation) is to be made or not.

If this is enabled, name reclamation will be performed on behalf of a previous listener, even if it is still running and accepting connections, thereby displacing it from the socket name so that the newly created listener could take its place.

This is disabled by default.

Platform-specific behavior

Unix

On Unix, this deletes the socket file if an AddrInUse error is encountered. The previous listener, if it is still listening on its socket, is not (and in fact cannot be) notified of this in any way. Note that, by default, this will spin for an unbounded amount of time if there is contention – set max_spin_time if this is undesirable.

The deletion suffers from an unavoidable TOCTOU race between the AddrInUse error being observed and the socket file being deleted, since another process may replace the socket file with a different file, causing Interprocess to delete that file instead. Note that this generally has no inadvertent privilege escalation implications, as the privileges required for renaming a file are the same as the ones required for deleting it, but the behavior may still be surprising in this (admittedly rather artificial) edge case.

Windows

Does nothing (meaning the error goes unhandled), as named pipes cannot be overwritten.

pub fn max_spin_time(self, max_spin_time: Duration) -> Self

Sets the maximum cumulative amount of time for which listener creation may spin in retry loops.

Spinning under contention is, of course, avoided whenever possible, but certain features simply can’t be implemented without retry loops that have to loop for up to however long contention persists. If you’d like to limit the duration for which listener creation can be delayed by other processes, including potentially untrusted ones, set this option to a value that you consider reasonably low.

Platform-specific behavior

Unix

Made use of in the implementation of try_overwrite.

Windows

Currently not used for anything.

impl ListenerOptions<'_>

Listener constructors.

pub fn create_sync(self) -> Result<Listener>

Creates a Listener, binding it to the specified local socket name.

On platforms where there are multiple available implementations, this dispatches to the appropriate implementation based on where the name points to.

pub fn create_sync_as<L: Listener>(self) -> Result<L>

Creates the given type of listener, binding it to the specified local socket name.

pub fn create_tokio(self) -> Result<TokioListener>

Available on crate feature tokio only.

Creates a Tokio Listener, binding it to the specified local socket name.

On platforms where there are multiple available implementations, this dispatches to the appropriate implementation based on where the name points to.

pub fn create_tokio_as<L: Listener>(self) -> Result<L>

Available on crate feature tokio only.

Creates the given type of listener, binding it to the specified local socket name.

Trait Implementations

impl Debug for ListenerOptions<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ListenerOptions<'_>

fn default() -> Self

Returns the “default value” for a type.

impl ListenerOptionsExt for ListenerOptions<'_>

Available on Unix only.

fn mode(self, mode: mode_t) -> Self

Sets the file mode (Unix permissions) to be applied to the socket file. This will authenticate clients using their process credentials according to the write bits of the mode; the read and execute bits are ignored by the OS and serve a cosmetic purpose.

impl TryClone for ListenerOptions<'_>

fn try_clone(&self) -> Result<Self>

Clones self, possibly returning an error.