Function netio_unbuffered_publishv_usr

Function Documentation

int netio_unbuffered_publishv_usr(struct netio_unbuffered_publish_socket *socket, netio_tag_t tag, struct iovec *iov, size_t count, uint64_t *key, int flags, struct netio_subscription_cache *cache, uint64_t usr, uint8_t usr_size)

Publishes a message on an unbuffered publish socket.

The message is given as a scatter/gather buffer (struct iovec). The caller has to ensure the validity of the buffer until the transfer is complete. A transfer is complete when the socket’s msg_published callback has been called. A key can be passed to the call to identify the publication. The key will be passed in the msg_published callback.

The msg_published callback will only be called if the message has been sent successfully to all subscribed endpoints.

The call may return NETIO_STATUS_AGAIN if one of the sockets connections yields NETIO_STATUS_AGAIN. In this case it is the user’s responsibility to call netio_unbuffered_publishv again with the NETIO_REENTRY flag.

Parameters:

  • socket – The socket to publish on

  • tag – The tag under which to publish

  • iov – Message data iov

  • count – IOV count

  • key – Key that will be passed to the callback on successful publish of the message. This is an input-output parameter. In case the function returns NETIO_STATUS_PARTIAL, ‘key’ is used as storage to track the completion data for the given tag. If netio_unbuffered_publishv is called again with the NETIO_REENTRY flag, ‘key’ must remain unchanged. In other words, for a given tag, ‘key’ is only set by the user before the initial call to netio_unbuffered_publishv without the NETIO_REENTRY flag.

  • flags – NETIO_REENTRY publishing of this message was attempted before and resulted in NETIO_STATUS_AGAIN. Calling publish with this flag will only send on connections where the message was previously unpublished.

  • cache – Optional user-supplied cache for the subsctiption table lookup.

  • usr – Up to 8 byte of data that are transmitted as beginning of the message. This allows the user to add a short header to a message without having to allocate bufferspace for it.

  • usr_size – Size of the usr header field. Set to 0 if no header is required. The maximum header size is 8.

Returns:

NETIO_STATUS_OK If the message was published successfully to all subscribed endpoints

Returns:

NETIO_STATUS_OK_NOSUB No ongoing subscriptions to publish the given message

Returns:

NETIO_STATUS_AGAIN If not enough resources are available to proceed with the operation. No data were sent to any endpoint. The user should try again with the exact same parameters.

Returns:

NETIO_STATUS_PARTIAL The message was sent to some of the subscribed endpoints, but not all. The user should try again, and additionally set the NETIO_REENTRY flag. Users must take care not to overwrite the key parameter, which is used by the function call to track the operation status.

Returns:

NETIO_ERROR_MAX_IOV_EXCEEDED Too many iovec entries, try with less.