XPIO

Create a socket of the specified type. Supported types are "TCP" and "UDP". It returns the socket on success, or nil, <error> on failure.

See Socket Objects, below.

Create a new task queue. Task queues keep track of task objects (Lua tables) that are waiting for events.

Tasks are placed on the queue by “When” Functions.

tqueue:wait(timeout) returns the tasks whose events have occurred.

Sets task as the current task. The current task is used by Blocking functions to schedule resumption of the running coroutine before it yields.

Returns the current task.

Returns the current time in a format compatible with the timeout in tqueue:wait(timeout). Units are in seconds, and the reference point is not specified.

Creates and returns two connected stream socket objects. Data written to one is readable from the other and vice-versa.

On error, it returns nil and an error message.

Create and return a socket object bound to a specified file descriptor. For example, xpio.fdopen(1) will return an object that can be used to write to stdout.

Creates a pipe and returns the two endpoints (read side followed by write side).

On error, it returns nil and an error message.

Create a new process, returning a process object (see Process Objects).

• args is an array of strings that describes the arguments for the new process. These strings args[1...#args] will be available to an invoked C program as argv[0...argc-1].

  The first argument provides the default for args.exe (see below).

• env is the environment for the new process in the form of a table mapping names to values. Environment names are case sensitive and may not contain = or null (\0) characters. Values may not contain null characters.

• files is a sparse array describing what files will be granted to the new process.

  Each key in this table is a file number (descriptor) in the child process. The value associated with each key identifies which of the parent's files will appear at that file number. These can be file objects (created via socket, fdopen, pipe, etc.) or file numbers. Any file objects provided will be closed in the parent process after the child process has been spawned.

  For example, in this case:

  { [0] = 0, [1] = 2, [2] = writePipe }
  

  the child's STDIN will be the same as that of its parent, its STDOUT will be the parent's STDERR, and its STDERR will be writePipe, and on success, writePipe will be closed in the parent process.

  All files granted to the child process will be reset to blocking mode, which is what most command-line programs will require. Unfortunately, due to OS limitations, the blocking/non-blocking property is a characteristic of the file, not of the process or the software using it, so after a file is passed to a child process it should not be directly accessed via XPIO's socket API. (This is why granted file objects are closed.)

  Files granted to the child process will be reset to blocking mode, and will be closed in the current process.

• attrs is a table mapping field names to values, all of which are optional:

  • attrs.exe gives the name of an executable file to be used as the

    code image for the child process. If this value is nil, args[1] will be used.

    If the file name does not contain a “/”, PATH is searched.

  • [TODO] attrs.cwd gives the current working directory for the child process.

  • [TODO] attrs.pgroup: When this value is a process object, it is the leader of a process group which the spawned process should be placed in. When this value is true, the spawned process will be placed in a new process group with itself as the leader.

Note that, unlike posix_spawn(), several values are not inherited from the current process. The file argument explicitly names each descriptor for the new process. Also, the signal mask and signal handlers are set to defaults (using POSIX_SPAWN_SIGDEF).

Unresolved issues:

• umask is inherited by the child process. umask is essentially an invisible input parameter to command-line tools, indicating how they are expected to create files, so in at least some contexts inheriting the parent's umask is the right thing. An attrs.umask field could allow more control.

• ctty (Controlling terminal) is inherited. This allows the process to gain access to the terminal by calling open("/dev/tty").

• Membership in process groups and sessions is inherited. This is probably the right thing for most server and client applications. Special programs like shells would call setsid() to make themselves a session leader, and assign new processes to pgroups.

• Sandboxing: Specifying resource limits, new UID & groups, and related operations are not currently supported.

A table containing the environment variables of the current process. This table is initialized when the xpio library is loaded.

Terminate execution of process.

Wait for the process to exit and return its exit status. It returns one of the following values:

This is a Blocking function that must be called from a coroutine. Its corresponding “try” and “when” functions are process:try_wait() and process:when_wait().

Wait until one or more tasks are ready.

Timeout is the maximum amount of time to wait, in seconds. A timeout of nil or false means “no timeout”.

If there are no tasks queued and there is no timeout, wait() returns nil, indicating “nothing to wait on”.

Otherwise, it returns an array that contains the tasks that are ready to run. This array may be empty if the timeout expired before any tasks were ready. All tasks returned will have been removed from the tqueue, and their _dequeue field will be nil.

Return true if there are no tasks waiting in tqueue.

Bind socket to a local address. addr is a string in the Address Format described below.

IP address 0 (or 0.0.0.0) indicates “any interface” (POSIX's INADDR_ANY). Port number 0 indicates “pick any available port”.

Listen for inbound TCP connections.

Backlog, if provided, is an integer giving the size of the accept queue.

Initiate a TCP connection, returning a new TCP object. addr is a string in the Address Format described below.

This is a Blocking function that must be called from a coroutine. Its “try” and “when” functions are socket:try_connect() and socket:when_write().

Accept an incoming connection, returning a new socket. In “retry” cases, the caller should retry when the socket is readable.

This is a Blocking function that must be called from a coroutine. Its “try” and “when” functions are socket:try_accept() and socket:when_read().

Get the bound local address of socket. On success, returns a string in the XPIO's Address Format.

Get the IP address and port of the peer connected to socket. On success, returns a string in the XPIO's Address Format.

Close the socket.

size is the maximum number of bytes to be consumed.

The “end” condition implies that the peer gracefully closed (or shutdown writing) and all sent bytes have been received. In the error case, the <string> returned is the result of strerror().

When size is zero, the function immediately returns an empty string; no error conditions are reported. (This masks behavior undefined by POSIX).

This is a Blocking function that must be called from a coroutine. Its corresponding “try” and “when” functions are process:try_read() and process:when_read().

data is a string (or number) to be written to the socket.

On success the number of bytes written are returned. This might be less than the size of data. The “retry” condition indicates that the caller should retry when the socket is writable.

When data is an empty string, the results are not clearly defined. Refer to POSIX or specific implementations.

This is a Blocking function that must be called from a coroutine. Its corresponding “try” and “when” functions are process:try_write() and process:when_write().

Query a socket option. See xpio.setsockopt, below.

Set a socket option.

xpio.setsockopt provides the functionality of setsockopt, fcntl, and various other OS-level functions. Each option is named by a string that corresponds to its POSIX name.

what is a string describing which end of the connection to shut down. A w in the string means that writing will be shut down (the peer will see and “end of stream” indication when it tries to read). An r in the stream will cause reading to be shut down.

Return the file descriptor number associated with socket.