Skip to content

Latest commit

 

History

History
79 lines (50 loc) · 3.43 KB

demi_pushto.md

File metadata and controls

79 lines (50 loc) · 3.43 KB
Raw

demi_pushto()

Name

demi_pushto - Asynchronously pushes a scatter-gather array to a socket I/O queue.

Synopsis

#include <demi/libos.h>
#include <sys/socket.h> /* For struct sockaddr and socklen_t. */

int demi_pushto(demi_qtoken_t *qt_out, int sockqd, const demi_sgarray_t *sga, const struct sockaddr *dest_addr, socklen_t size);

Description

demi_pushto() asynchronously pushes a scatter-gather array to a socket I/O queue. It works with connection-mode or connectionless-mode socket.

If the socket is a connectionless-mode socket, the message shall be sent to the address specified by dest_addr if no pre-specified peer address has been set. If a peer address has been pre-specified, either the message shall be sent to the address specified by dest_addr (overriding the pre-specified peer address), or the function shall return -1 and set errno to [EISCONN].

The sockqd parameter is the I/O queue descriptor that is associated with the target socket I/O queue.

The sga parameter points to the scatter-gather array that is being pushed. For information on scatter-gather arrays, see demi_sgaalloc().

The dest_addr parameter points to information concerning the destination address. The sockaddr structure has a genetic format and its only purpose is to cast the structure pointer passed in dest_addr, in order to avoid compiler warnings. The length and the format of actual socket address depends on the address family of the socket.

The size parameter specifies the size (in bytes) of the address structure pointed to by dest_addr.

The qt_out parameter points to the location where the queue token for the demi_pushto() operation should be stored. An application may use this queue token with demi_wait() or demi_wait_any() to block until the operation effectively completes.

demi_pushto() avoids copying, so the application must not modify or free any memory referenced in the scatter-gather array, until the asynchronous push operation completes. Some libOSes offer free-protection, which ensures memory referenced by the scatter-gather array is not released until the operation completes, even if the application releases that memory area. However, applications should not rely on this feature.

Return Value

On success, zero is returned. On error, a positive error code is returned.

Errors

On error, one of the following positive error codes is returned:

  • EINVAL - The dest_addr argument does not point to a valid socket address structure.
  • EINVAL - The socket address size size is not valid.
  • EINVAL - The sga argument does not point to a valid scatter-gather array.
  • EINVAL - The scatter-gather array pointed to by sga refers to a zero-length buffer.
  • EBADF - sockqd does not refer to a socket I/O queue.
  • EAGAIN - Demikernel failed to create an asynchronous co-routine to handle the demi_pushto() operation.

Conforming To

The socket address structure, the socket length type and error codes are conformant to POSIX.1-2017.

Bugs

Demikernel may fail with error codes that are not listed in this manual page.

Issue #137 - demi_pushto() does not work on some LibOSes.

Disclaimer

Any behavior that is not documented in this manual page is unintentional and should be reported.

See Also

demi_push(), demi_sgaalloc(), demi_wait() and demi_wait_any().