Inherits from NSObject
Declared in CURLMulti.h

Overview

Wrapper for a curl_multi handle. In general you shouldn’t use this class directly – use the extensions in NSURLRequest+CURLHandle instead, and work with normal NSURLConnections.

CURLProtocol uses the global sharedInstance to implement the NSURLRequest/NSURLConnection integration.

There’s nothing to stop you making other instances if you want to – it’s just not really necessary, particularly as we don’t expose the curl multi externally.

This class works by setting up a serial GCD queue to process all events associated with the multi. We add gcd dispatch sources for each socket that the multi makes, and use them to notify curl when something happens that needs attention.

Tasks

  • + sharedInstance

    Return a default instance. Don’t call startup or shutdown on this instance – startup will already have been called, and shutting it down will be terminal since it’s shared by everything.
  • – startup

    Prepare the multi for work. Needs to be called once before addHandle is called. Should be matched with a call to shutdown before the multi is destroyed.
  • – shutdown

    Shut down the multi and clean up all resources that it was using.
  • – manageHandle:

    Assign a CURLHandle to the multi to manage. CURLHandle uses this method internally when you call loadRequest:withMulti: on a handle, so generally you don’t need to call it directly. The multi will retain the handle for as long as it needs it, but will silently release it once the handle’s upload/download has completed or failed.
  • – stopManagingHandle:

    This removes the handle from the multi. * It is safe to call this method for a handle that has already been cancelled, or has completed, (or indeed was never managed by the multi). Doing so will simply do nothing.
  • – updateSource:type:socket:raw:required:

    Update the dispatch source for a given socket and type.

Class Methods

sharedInstance

Return a default instance. Don’t call startup or shutdown on this instance – startup will already have been called, and shutting it down will be terminal since it’s shared by everything.

+ (CURLMulti *)sharedInstance

Return Value

The shared instance.

Declared In

CURLMulti.h

Instance Methods

manageHandle:

Assign a CURLHandle to the multi to manage. CURLHandle uses this method internally when you call loadRequest:withMulti: on a handle, so generally you don’t need to call it directly. The multi will retain the handle for as long as it needs it, but will silently release it once the handle’s upload/download has completed or failed.

- (void)manageHandle:(CURLHandle *)handle

Parameters

handle

The handle to manage. Will be retained by the multi.

Declared In

CURLMulti.h

shutdown

Shut down the multi and clean up all resources that it was using.

- (void)shutdown

Declared In

CURLMulti.h

startup

Prepare the multi for work. Needs to be called once before addHandle is called. Should be matched with a call to shutdown before the multi is destroyed.

- (void)startup

Declared In

CURLMulti.h

stopManagingHandle:

This removes the handle from the multi. * It is safe to call this method for a handle that has already been cancelled, or has completed, (or indeed was never managed by the multi). Doing so will simply do nothing.

- (void)stopManagingHandle:(CURLHandle *)handle

Parameters

handle

The handle to cancel. Should have previously been added with manageHandle:.

Discussion

To cancel the handle, call [handle cancel] instead – it will end up calling this method too, if the handle was being managed by a multi.

Declared In

CURLMulti.h

updateSource:type:socket:raw:required:

Update the dispatch source for a given socket and type.

- (dispatch_source_t)updateSource:(dispatch_source_t)source type:(dispatch_source_type_t)type socket:(CURLSocket *)socket raw:(int)raw required:(BOOL)required

Parameters

source

The current dispatch source for the given type

type

Is this the source for reading or writing?

socket

The CURLSocket object that owns the source.

raw

The raw system socket that the dispatch source should be monitoring.

required

Is the source required? If not, an existing source will be cancelled. If required and the source parameter is nil, and new one will be created.

Return Value

The new/updated dispatch source.

Discussion

Warning: The routine is used internally by / CURLSocket, and shouldn’t be called from your code.

Declared In

CURLMulti.h