Document how to use tokio-uds with tokio-proto

[nicholasbishop]

The tokio documentation has a simple example of setting up a TCP service with tokio-proto: https://tokio.rs/docs/getting-started/simple-server/#configure-and-run

I'm trying to understand how to do something similar with unix sockets, but it's not clear to me how to connect my implementation of a Service with a UnixStream.

[alexcrichton]

Sounds reasonable to me! The TcpServer code is actually pretty simple and basically just boils down to this function. The trick is the BindServer trait which typically takes any I/O object, including a UnixStream.

[nicholasbishop]

The documentation for BindServer says "This trait is not intended to be implemented directly". Is this an exception to that rule, or should one of the other traits suggested in that documentation be used?

[alexcrichton]

@nicholasbishop oh yeah it's not implemented directly, but it can be called with a UnixStream. Most implementations of it (transitively through the impl you see) are generic over T: Io

[nicholasbishop]

I think I am still lost :) I was able to make a modified copy of tcp_server.rs that serves over a unix socket, but I don't feel any closer to understanding why tcp_server.rs is implemented the way it is.

When you say "it's not implemented directly, but it can be called with a UnixStream", does "it" mean the BindServer trait? If so, what does it mean to call the trait with a UnixStream?

At a higher level, what is the point of the BindServer trait, as opposed to a more direct Server trait?

Actually, where are the other four traits mentioned in BindServer's documentation? It refers to pipeline::Server and three others, but the pipeline module doesn't document a trait of that name.

[alexcrichton]

There are a number of main "proto" traits

• pipeline::ServerProto
• multiplex::ServerProto
• streaming::pipeline::ServerProto
• streaming::multiplex::ServerProto

These are intended to be implemented by protocol authors, and work in the various styles as described by the modules.

The BindServer trait then has a number of blanket impls to implement itself for free on your protocol once you implement one or more of the above Proto traits. The purpose of BindServer is to instantiate the protocol internals for you, e.g. the pipeline/multiplex dispatch.

The bind_server method takes any I/O object and spawns a future that handles the connection. This I/O object can be a unix stream.

The tl;dr; of TcpServer is:

• Create a Core
• Create a TcpListener
• Crate a loop over each accepted connection
• For each accepted connection, call bind_server

Does that help clear things up?

[ZoeyR]

This is a bit of a late response, but I just published a crate that makes a UnixServer and UnixClient with a similar API to tokio-proto. The documentation is lacking at the moment. But it should work in the same way.

[alexcrichton]

Thanks @dgriffen!

[nicholasbishop]

Nice! I have my tokio experimentation on the back burner but I'll definitely give it a try when I get back to it. Thanks for putting that crate up.

[fullmetaldr]

Has there been any progress on this issue? I currently have a project that uses a nanomsg as the networking library since I need to switch between TCP and UDS connections for different scenarios.

However, I'm looking to move away from that library for several reasons and Tokio in general looks fantastic for my purposes, I just wanted to make sure I can create UDS connections without problems first, and I have yet to find an example of how this works.

Any documentation you could point me to?