Struct glommio::net::UnixListener
source · pub struct UnixListener { /* private fields */ }
Expand description
A Unix socket server, listening for connections.
After creating a UnixListener by binding it to a socket address, it listens
for incoming Unix connections. These can be accepted by calling accept
or shared_accept
, or by iterating over the Incoming iterator returned by
incoming
.
A good networking architecture within a thread-per-core model needs to take into account parallelism and spawn work into multiple executors. If everything happens inside the same Executor, then at most one thread is used. Sometimes this is what you want: you may want to dedicate a CPU entirely for networking, or even use specialized ports for each CPU of the application, but most likely it isn’t.
There are so far only one approach to load balancing possible with the
UnixListener
:
- It is possible to use
shared_accept
instead ofaccept
: that returns an object that implementsSend
. You can then use ashared_channel
to send the accepted connection into multiple executors. The object returned byshared_accept
can then be bound to its executor withbind_to_executor
, at which point it becomes a standardUnixStream
.
The socket will be closed when the value is dropped.
Implementations§
source§impl UnixListener
impl UnixListener
sourcepub fn bind<A: AsRef<Path>>(addr: A) -> Result<UnixListener, ()>
pub fn bind<A: AsRef<Path>>(addr: A) -> Result<UnixListener, ()>
Creates a Unix listener bound to the specified address.
Binding with port number 0 will request an available port from the OS.
This method sets the ReusePort option in the bound socket, so it is designed to be called from multiple executors to achieve parallelism.
§Examples
use glommio::{net::UnixListener, LocalExecutor};
let ex = LocalExecutor::default();
ex.run(async move {
let _listener = UnixListener::bind("/tmp/named").unwrap();
});
Accepts a new incoming Unix connection and allows the result to be sent to a foreign executor
This is similar to accept
, except it returns an
AcceptedUnixStream
instead of a UnixStream
.
AcceptedUnixStream
implements Send
, so it can be safely sent
for processing over a shared channel to a different executor.
This is useful when the user wants to do her own load balancing across multiple executors instead of relying on the load balancing the OS would do with the ReusePort property of the bound socket.
§Examples
use glommio::{net::UnixListener, LocalExecutor};
let ex = LocalExecutor::default();
ex.run(async move {
let listener = UnixListener::bind("/tmp/named").unwrap();
let _stream = listener.shared_accept().await.unwrap();
});
sourcepub async fn accept(&self) -> Result<UnixStream, ()>
pub async fn accept(&self) -> Result<UnixStream, ()>
Accepts a new incoming Unix connection in this executor
This is similar to calling shared_accept
and bind_to_executor
in
a single operation.
If this connection once accepted is to be handled by the same executor in which it was accepted, this version is preferred.
§Examples
use futures_lite::stream::StreamExt;
use glommio::{net::UnixListener, LocalExecutor};
let ex = LocalExecutor::default();
ex.run(async move {
let listener = UnixListener::bind("/tmp/named").unwrap();
let _stream = listener.accept().await.unwrap();
});
sourcepub fn incoming(
&self
) -> impl Stream<Item = Result<UnixStream, ()>> + Unpin + '_
pub fn incoming( &self ) -> impl Stream<Item = Result<UnixStream, ()>> + Unpin + '_
Creates a stream of incoming connections
§Examples
use futures_lite::stream::StreamExt;
use glommio::{net::UnixListener, LocalExecutor};
let ex = LocalExecutor::default();
ex.run(async move {
let listener = UnixListener::bind("/tmp/named").unwrap();
let mut incoming = listener.incoming();
while let Some(conn) = incoming.next().await {
// handle
}
});
sourcepub fn local_addr(&self) -> Result<SocketAddr, ()>
pub fn local_addr(&self) -> Result<SocketAddr, ()>
Returns the socket address of the local half of this Unix connection.
§Examples
use glommio::{net::UnixListener, LocalExecutor};
let ex = LocalExecutor::default();
ex.run(async move {
let listener = UnixListener::bind("/tmp/named").unwrap();
println!("Listening on {:?}", listener.local_addr().unwrap());
});