Share data between handles

All easy handles added to the same multi handle automatically share
cookies, , dns cache and SSL
session id cache.

libcurl has a generic “sharing interface”, where the application creates a
“share object” that then holds data that can be shared by any number of easy
handles. The data is then stored and read from the shared object instead of
kept within the handles that are sharing it.

The shared object can be set to share all or any of cookies, connection cache,
dns cache and SSL session id cache.

For example, setting up the share to hold cookies and dns cache:

Transfers done with this handle will thus use and store its cookie and
dns information in the share handle. You can set several easy handles to
share the same share object.

- set this bit to share cookie jar. Note that each
easy handle still needs to get its cookie “engine” started properly to start
using cookies.

CURL_LOCK_DATA_DNS - the DNS cache is where libcurl stores addresses for
resolved host names for a while to make subsequent lookups faster.

- the SSL session ID cache is where libcurl store
resume information for SSL connections to be able to resume a previous
connection faster.

If you want have the share object shared by transfers in a multi-threaded
environment. Perhaps you have a CPU with many cores and you want each core to
run its own thread and transfer data, but you still want the different
transfers to share data. Then you need to set the mutex callbacks.

If you don’t use threading and you know you access the shared object in a
serial one-at-a-time manner you don’t need to set any locks. But if there is
ever more than one transfer that access share object at a time, it needs to
get mutex callbacks setup to prevent data destruction and possibly even
crashes.

Since libcurl itself doesn’t know how to lock things or even what threading
model you’re using, you must make sure to do mutex locks that only allows one
access at a time. A lock callback for a pthreads-using application could look
similar to:

With the corresponding unlock callback could look like: