tarantool / tarantool / 5807649746

88%

push

github

lua/socket: introduce socket.socketpair

The new function is a wrapper around the socketpair system call.
It takes the same arguments as the socket constructor and returns
two socket objects representing the two ends of the newly created
socket pair on success.

It may be useful for establishing a communication channel between
related processes.

Closes #8927

@TarantoolBot document
Title: Document new socket functions

Two socket module functions and one socket object method were added to
Tarantool 3.0:

- `socket.from_fd(fd)`: constructs a socket object from the file
  descriptor number. Returns the new socket object on success. Never
  fails. Note, the function doesn't perform any checks on the given
  file descriptor so technically it's possible to pass a closed file
  descriptor or a file descriptor that refers to a file, in which case
  the new socket object methods may not work as expected.

- `socket:detach()`: like `socket:close()` but doesn't close the socket
  file descriptor, only switches the socket object to the closed state.
  Returns nothing. If the socket was already detached or closed, raises
  an exception.

  Along with `socket.from_fd`, this method may be used for transferring
  file descriptor ownership from one socket to another:

  ```Lua
  local socket = require('socket')
  local s1 = socket('AF_INET', 'SOCK_STREAM', 'tcp')
  local s2 = socket.from_fd(s1:fd())
  s1:detach()
  ```

- `socket.socketpair(domain, type, proto)`: a wrapper around the
  [`socketpair`][1] system call. Returns two socket objects representing
  the two ends of the new socket pair on success. On failure, returns
  nil and sets [`errno`][2].

  Example:

  ```Lua
  local errno = require('errno')
  local socket = require('socket')
  local s1, s1 = socket.socketpair('AF_UNIX', 'SOCK_STREAM', 0)
  if not s1 then
      error('socketpair: ' .. errno.strerror())
  end
  s1:send('foo')
  assert(s2:recv() == 'foo')
  s1:close()
  s2:close()
  ```

[1]: https://ma... (continued)

63541 of 115244 branches covered (55.14%)

95196 of 110562 relevant lines covered (86.1%)

2878851.26 hits per line