Socket.sendMessages

Send multiple data messages from socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see Socket.send, Socket.sendTo, and Socket.sendMessage.

messages must point to an array of GOutputMessage structs and num_messages must be the length of this array. Each GOutputMessage contains an address to send the data to, and a pointer to an array of GOutputVector structs to describe the buffers that the data to be sent for each message will be gathered from. Using multiple GOutputVectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to Socket.send. Sending multiple messages in one go avoids the overhead of making a lot of syscalls in scenarios where a lot of data packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), or where the same data needs to be sent to multiple recipients.

flags modify how the message is sent. The commonly available arguments for this are available in the GSocketMsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too.

If the socket is in blocking mode the call will block until there is space for all the data in the socket queue. If there is no space available and the socket is in non-blocking mode a G_IO_ERROR_WOULD_BLOCK error will be returned if no data was written at all, otherwise the number of messages sent will be returned. To be notified when space is available, wait for the G_IO_OUT condition. Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from Socket.send even if you were previously notified of a G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.)

On error -1 is returned and error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned.

class Socket
int
sendMessages

Parameters

messages GOutputMessage[]

an array of GOutputMessage structs

flags int

an int containing GSocketMsgFlags flags, which may additionally contain other platform specific flags

cancellable Cancellable

a GCancellable or NULL

Return Value

Type: int

number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than num_messages if the socket is non-blocking or if num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to send the remaining messages.

Throws

GException on failure.

Meta

Since

2.44