send_messages
Description:
public int send_messages (OutputMessage[] messages, int flags, Cancellable? cancellable = null) throws Error
Send multiple data messages from this in one go.
This is the most complicated and fully-featured version of this call. For easier use, see send, send_to, and send_message.
messages must point to an array of OutputMessage structs and
messages.length must be the length of this array. Each OutputMessage
contains an address to send the data to, and a pointer to an array of OutputVector
structs to describe the buffers that the data to be sent for each message will be gathered from. Using multiple
OutputVectors is more memory-efficient than manually copying data from multiple
sources into a single buffer, and more network-efficient than making multiple calls to
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
SocketMsgFlags 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 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 throws 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.
Parameters:
| this |
a Socket |
| messages |
an array of OutputMessage structs |
| flags |
an int containing SocketMsgFlags flags, which may additionally contain other platform specific flags |
| cancellable |
a gcancellable or null |
| num_messages |
the number of elements in |
Returns:
|
number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than |