luo980/libuv
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify that uv_pipe_t is a pipe

Browse Source 
Some people have misread this section to imply that libuv does not
support Unix `pipe` objects, while it only should be saying that the
UV_CREATE_PIPE makes a socketpair. Clarify the docs to say specifically
that `uv_pipe_t` represents any local file stream.

PR-URL: https://github.com/libuv/libuv/pull/2607
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>
This commit is contained in:
Jameson Nash 2020-01-07 13:26:00 -05:00
parent e1fad5a37f
commit 02a36bb3ba
2 changed files with 28 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/src/guide/processes.rst
View File

@ -243,26 +243,35 @@ is great. Just be warned that creating processes is a costly task.
.. _pipes:
Pipes
-----
libuv's ``uv_pipe_t`` structure is slightly confusing to Unix programmers,
because it immediately conjures up ``|`` and `pipe(7)`_. But ``uv_pipe_t`` is
not related to anonymous pipes, rather it is an IPC mechanism. ``uv_pipe_t``
can be backed by a `Unix Domain Socket`_ or `Windows Named Pipe`_ to allow
multiple processes to communicate. This is discussed below.
.. _pipe(7): http://man7.org/linux/man-pages/man7/pipe.7.html
.. _Unix Domain Socket: http://man7.org/linux/man-pages/man7/unix.7.html
.. _Windows Named Pipe: https://docs.microsoft.com/en-us/windows/win32/ipc/named-pipes
Parent-child IPC
++++++++++++++++
----------------
A parent and child can have one or two way communication over a pipe created by
settings ``uv_stdio_container_t.flags`` to a bit-wise combination of
``UV_CREATE_PIPE`` and ``UV_READABLE_PIPE`` or ``UV_WRITABLE_PIPE``. The
read/write flag is from the perspective of the child process.
read/write flag is from the perspective of the child process. In this case,
the ``uv_stream_t* stream`` field must be set to point to an initialized,
unopened ``uv_pipe_t`` instance.
New stdio Pipes
+++++++++++++++
The ``uv_pipe_t`` structure represents more than just `pipe(7)`_ (or ``|``),
but supports any streaming file-like objects. On Windows, the only object of
that description is the `Named Pipe`_. On Unix, this could be any of `Unix
Domain Socket`_, or derived from `mkfifo(1)`_, or it could actually be a
`pipe(7)`_. When ``uv_spawn`` initializes a ``uv_pipe_t`` due to the
`UV_CREATE_PIPE` flag, it opts for creating a `socketpair(2)`_.
This is intended for the purpose of allowing multiple libuv processes to
communicate with IPC. This is discussed below.
.. _pipe(7): http://man7.org/linux/man-pages/man7/pipe.7.html
.. _mkfifo(1): http://man7.org/linux/man-pages/man1/mkfifo.1.html
.. _socketpair(2): http://man7.org/linux/man-pages/man2/socketpair.2.html
.. _Unix Domain Socket: http://man7.org/linux/man-pages/man7/unix.7.html
.. _Named Pipe: https://docs.microsoft.com/en-us/windows/win32/ipc/named-pipes
Arbitrary process IPC
+++++++++++++++++++++

7
docs/src/pipe.rst
View File

@ -4,8 +4,8 @@
:c:type:`uv_pipe_t` --- Pipe handle
===================================
Pipe handles provide an abstraction over local domain sockets on Unix and named
pipes on Windows.
Pipe handles provide an abstraction over streaming files on Unix (including
local domain sockets, pipes, and FIFOs) and named pipes on Windows.
:c:type:`uv_pipe_t` is a 'subclass' of :c:type:`uv_stream_t`.
@ -34,7 +34,8 @@ API
.. c:function:: int uv_pipe_init(uv_loop_t* loop, uv_pipe_t* handle, int ipc)
Initialize a pipe handle. The `ipc` argument is a boolean to indicate if
this pipe will be used for handle passing between processes.
this pipe will be used for handle passing between processes (which may
change the bytes on the wire).
.. c:function:: int uv_pipe_open(uv_pipe_t* handle, uv_file file)