Struct curl::multi::Multi

pub struct Multi { /* private fields */ }

A multi handle for initiating multiple connections simultaneously.

This structure corresponds to CURLM in libcurl and provides the ability to have multiple transfers in flight simultaneously. This handle is then used to manage each transfer. The main purpose of a CURLM is for the application to drive the I/O rather than libcurl itself doing all the blocking. Methods like action allow the application to inform libcurl of when events have happened.

Lots more documentation can be found on the libcurl multi tutorial where the APIs correspond pretty closely with this crate.

Implementations

impl Multi

pub fn new() -> Multi

Creates a new multi session through which multiple HTTP transfers can be initiated.

pub fn socket_function<F>(&mut self, f: F) -> Result<(), MultiError> where
    F: FnMut(Socket, SocketEvents, usize) + Send + 'static, 

Set the callback informed about what to wait for

When the action function runs, it informs the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback. The callback gets status updates with changes since the previous time the callback was called. See action for more details on how the callback is used and should work.

The SocketEvents parameter informs the callback on the status of the given socket, and the methods on that type can be used to learn about what’s going on with the socket.

The third usize parameter is a custom value set by the assign method below.

pub fn assign(&self, socket: Socket, token: usize) -> Result<(), MultiError>

Set data to associate with an internal socket

This function creates an association in the multi handle between the given socket and a private token of the application. This is designed for action uses.

When set, the token will be passed to all future socket callbacks for the specified socket.

If the given socket isn’t already in use by libcurl, this function will return an error.

libcurl only keeps one single token associated with a socket, so calling this function several times for the same socket will make the last set token get used.

The idea here being that this association (socket to token) is something that just about every application that uses this API will need and then libcurl can just as well do it since it already has an internal hash table lookup for this.

Typical Usage

In a typical application you allocate a struct or at least use some kind of semi-dynamic data for each socket that we must wait for action on when using the action approach.

When our socket-callback gets called by libcurl and we get to know about yet another socket to wait for, we can use assign to point out the particular data so that when we get updates about this same socket again, we don’t have to find the struct associated with this socket by ourselves.

pub fn timer_function<F>(&mut self, f: F) -> Result<(), MultiError> where
    F: FnMut(Option<Duration>) -> bool + Send + 'static, 

Set callback to receive timeout values

Certain features, such as timeouts and retries, require you to call libcurl even when there is no activity on the file descriptors.

Your callback function should install a non-repeating timer with the interval specified. Each time that timer fires, call either action or perform, depending on which interface you use.

A timeout value of None means you should delete your timer.

A timeout value of 0 means you should call action or perform (once) as soon as possible.

This callback will only be called when the timeout changes.

The timer callback should return true on success, and false on error. This callback can be used instead of, or in addition to, get_timeout.

pub fn pipelining(
    &mut self,
    http_1: bool,
    multiplex: bool
) -> Result<(), MultiError>

Enable or disable HTTP pipelining and multiplexing.

When http_1 is true, enable HTTP/1.1 pipelining, which means that if you add a second request that can use an already existing connection, the second request will be “piped” on the same connection rather than being executed in parallel.

When multiplex is true, enable HTTP/2 multiplexing, which means that follow-up requests can re-use an existing connection and send the new request multiplexed over that at the same time as other transfers are already using that single connection.

pub fn set_max_host_connections(&mut self, val: usize) -> Result<(), MultiError>

Sets the max number of connections to a single host.

Pass a long to indicate the max number of simultaneously open connections to a single host (a host being the same as a host name + port number pair). For each new session to a host, libcurl will open up a new connection up to the limit set by the provided value. When the limit is reached, the sessions will be pending until a connection becomes available. If pipelining is enabled, libcurl will try to pipeline if the host is capable of it.

pub fn set_max_total_connections(
    &mut self,
    val: usize
) -> Result<(), MultiError>

Sets the max simultaneously open connections.

The set number will be used as the maximum number of simultaneously open connections in total using this multi handle. For each new session, libcurl will open a new connection up to the limit set by the provided value. When the limit is reached, the sessions will be pending until there are available connections. If pipelining is enabled, libcurl will try to pipeline or use multiplexing if the host is capable of it.

pub fn set_max_connects(&mut self, val: usize) -> Result<(), MultiError>

Set size of connection cache.

The set number will be used as the maximum amount of simultaneously open connections that libcurl may keep in its connection cache after completed use. By default libcurl will enlarge the size for each added easy handle to make it fit 4 times the number of added easy handles.

By setting this option, you can prevent the cache size from growing beyond the limit set by you.

When the cache is full, curl closes the oldest one in the cache to prevent the number of open connections from increasing.

See set_max_total_connections for limiting the number of active connections.

pub fn set_pipeline_length(&mut self, val: usize) -> Result<(), MultiError>

Sets the pipeline length.

This sets the max number that will be used as the maximum amount of outstanding requests in an HTTP/1.1 pipelined connection. This option is only used for HTTP/1.1 pipelining, and not HTTP/2 multiplexing.

pub fn add(&self, easy: Easy) -> Result<EasyHandle, MultiError>

Add an easy handle to a multi session

Adds a standard easy handle to the multi stack. This function call will make this multi handle control the specified easy handle.

When an easy interface is added to a multi handle, it will use a shared connection cache owned by the multi handle. Removing and adding new easy handles will not affect the pool of connections or the ability to do connection re-use.

If you have timer_function set in the multi handle (and you really should if you’re working event-based with action and friends), that callback will be called from within this function to ask for an updated timer so that your main event loop will get the activity on this handle to get started.

The easy handle will remain added to the multi handle until you remove it again with remove on the returned handle - even when a transfer with that specific easy handle is completed.

pub fn add2<H>(&self, easy: Easy2<H>) -> Result<Easy2Handle<H>, MultiError>

Same as add, but works with the Easy2 type.

pub fn remove(&self, easy: EasyHandle) -> Result<Easy, MultiError>

Remove an easy handle from this multi session

Removes the easy handle from this multi handle. This will make the returned easy handle be removed from this multi handle’s control.

When the easy handle has been removed from a multi stack, it is again perfectly legal to invoke perform on it.

Removing an easy handle while being used is perfectly legal and will effectively halt the transfer in progress involving that easy handle. All other easy handles and transfers will remain unaffected.

pub fn remove2<H>(&self, easy: Easy2Handle<H>) -> Result<Easy2<H>, MultiError>

Same as remove, but for Easy2Handle.

pub fn messages<F>(&self, f: F) where
    F: FnMut(Message<'_>), 

Read multi stack informationals

Ask the multi handle if there are any messages/informationals from the individual transfers. Messages may include informationals such as an error code from the transfer or just the fact that a transfer is completed. More details on these should be written down as well.

pub fn action(&self, socket: Socket, events: &Events) -> Result<u32, MultiError>

Inform of reads/writes available data given an action

When the application has detected action on a socket handled by libcurl, it should call this function with the sockfd argument set to the socket with the action. When the events on a socket are known, they can be passed events. When the events on a socket are unknown, pass Events::new() instead, and libcurl will test the descriptor internally.

The returned integer will contain the number of running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. When you call action on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use messages to figure out which easy handle that completed.

The action function informs the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback function set with the socket_function method. They update the status with changes since the previous time the callback was called.

pub fn timeout(&self) -> Result<u32, MultiError>

Inform libcurl that a timeout has expired and sockets should be tested.

The returned integer will contain the number of running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. When you call action on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use messages to figure out which easy handle that completed.

Get the timeout time by calling the timer_function method. Your application will then get called with information on how long to wait for socket actions at most before doing the timeout action: call the timeout method. You can also use the get_timeout function to poll the value at any given time, but for an event-based system using the callback is far better than relying on polling the timeout value.

pub fn get_timeout(&self) -> Result<Option<Duration>, MultiError>

Get how long to wait for action before proceeding

An application using the libcurl multi interface should call get_timeout to figure out how long it should wait for socket actions - at most - before proceeding.

Proceeding means either doing the socket-style timeout action: call the timeout function, or call perform if you’re using the simpler and older multi interface approach.

The timeout value returned is the duration at this very moment. If 0, it means you should proceed immediately without waiting for anything. If it returns None, there’s no timeout at all set.

Note: if libcurl returns a None timeout here, it just means that libcurl currently has no stored timeout value. You must not wait too long (more than a few seconds perhaps) before you call perform again.

pub fn wait(
    &self,
    waitfds: &mut [WaitFd],
    timeout: Duration
) -> Result<u32, MultiError>

Block until activity is detected or a timeout passes.

The timeout is used in millisecond-precision. Large durations are clamped at the maximum value curl accepts.

The returned integer will contain the number of internal file descriptors on which interesting events occured.

This function is a simpler alternative to using fdset() and select() and does not suffer from file descriptor limits.

Example

use curl::multi::Multi;
use std::time::Duration;

let m = Multi::new();

// Add some Easy handles...

while m.perform().unwrap() > 0 {
    m.wait(&mut [], Duration::from_secs(1)).unwrap();
}

pub fn perform(&self) -> Result<u32, MultiError>

Reads/writes available data from each easy handle.

This function handles transfers on all the added handles that need attention in an non-blocking fashion.

When an application has found out there’s data available for this handle or a timeout has elapsed, the application should call this function to read/write whatever there is to read or write right now etc. This method returns as soon as the reads/writes are done. This function does not require that there actually is any data available for reading or that data can be written, it can be called just in case. It will return the number of handles that still transfer data.

If the amount of running handles is changed from the previous call (or is less than the amount of easy handles you’ve added to the multi handle), you know that there is one or more transfers less “running”. You can then call info to get information about each individual completed transfer, and that returned info includes Error and more. If an added handle fails very quickly, it may never be counted as a running handle.

When running_handles is set to zero (0) on the return of this function, there is no longer any transfers in progress.

Return

Before libcurl version 7.20.0: If you receive is_call_perform, this basically means that you should call perform again, before you select on more actions. You don’t have to do it immediately, but the return code means that libcurl may have more data available to return or that there may be more data to send off before it is “satisfied”. Do note that perform will return is_call_perform only when it wants to be called again immediately. When things are fine and there is nothing immediate it wants done, it’ll return Ok and you need to wait for “action” and then call this function again.

This function only returns errors etc regarding the whole multi stack. Problems still might have occurred on individual transfers even when this function returns Ok. Use info to figure out how individual transfers did.

pub fn fdset2(
    &self,
    read: Option<&mut fd_set>,
    write: Option<&mut fd_set>,
    except: Option<&mut fd_set>
) -> Result<Option<i32>, MultiError>

Extracts file descriptor information from a multi handle

This function extracts file descriptor information from a given handle, and libcurl returns its fd_set sets. The application can use these to select() on, but be sure to FD_ZERO them before calling this function as curl_multi_fdset only adds its own descriptors, it doesn’t zero or otherwise remove any others. The curl_multi_perform function should be called as soon as one of them is ready to be read from or written to.

If no file descriptors are set by libcurl, this function will return Ok(None). Otherwise Ok(Some(n)) will be returned where n the highest descriptor number libcurl set. When Ok(None) is returned it is because libcurl currently does something that isn’t possible for your application to monitor with a socket and unfortunately you can then not know exactly when the current action is completed using select(). You then need to wait a while before you proceed and call perform anyway.

When doing select(), you should use get_timeout to figure out how long to wait for action. Call perform even if no activity has been seen on the fd_sets after the timeout expires as otherwise internal retries and timeouts may not work as you’d think and want.

If one of the sockets used by libcurl happens to be larger than what can be set in an fd_set, which on POSIX systems means that the file descriptor is larger than FD_SETSIZE, then libcurl will try to not set it. Setting a too large file descriptor in an fd_set implies an out of bounds write which can cause crashes, or worse. The effect of NOT storing it will possibly save you from the crash, but will make your program NOT wait for sockets it should wait for…

pub fn raw(&self) -> *mut CURLM

Get a pointer to the raw underlying CURLM handle.

Trait Implementations

impl Debug for Multi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.