mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2024-11-21 01:16:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

INTERNALS: better markdown

Browse Source 
words with underscore need to be within `these`

Bug: https://github.com/curl/curl-www/issues/19
Reported-by : Jay Satiro
This commit is contained in:
Daniel Stenberg 2016-10-30 23:45:25 +01:00
parent 2e750ce452
commit 13f4913303
1 changed files with 48 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
docs/INTERNALS.md
View File

@ -858,7 +858,7 @@ for older and later versions as things don't change drastically that often.
## Curl_easy
The Curl_easy struct is the one returned to the outside in the external API
The `Curl_easy` struct is the one returned to the outside in the external API
as a "CURL *". This is usually known as an easy handle in API documentations
and examples.
@ -866,27 +866,27 @@ for older and later versions as things don't change drastically that often.
'connectdata' struct. When a transfer is about to be made, libcurl will
either create a new connection or re-use an existing one. The particular
connectdata that is used by this handle is pointed out by
Curl_easy->easy_conn.
`Curl_easy->easy_conn`.
Data and information that regard this particular single transfer is put in
the SingleRequest sub-struct.
When the Curl_easy struct is added to a multi handle, as it must be in order
to do any transfer, the ->multi member will point to the `Curl_multi` struct
it belongs to. The ->prev and ->next members will then be used by the multi
code to keep a linked list of Curl_easy structs that are added to that same
multi handle. libcurl always uses multi so ->multi *will* point to a
When the `Curl_easy` struct is added to a multi handle, as it must be in
order to do any transfer, the ->multi member will point to the `Curl_multi`
struct it belongs to. The ->prev and ->next members will then be used by the
multi code to keep a linked list of `Curl_easy` structs that are added to that
same multi handle. libcurl always uses multi so ->multi *will* point to a
`Curl_multi` when a transfer is in progress.
->mstate is the multi state of this particular Curl_easy. When
->mstate is the multi state of this particular `Curl_easy`. When
`multi_runsingle()` is called, it will act on this handle according to which
state it is in. The mstate is also what tells which sockets to return for a
specific Curl_easy when [`curl_multi_fdset()`][12] is called etc.
specific `Curl_easy` when [`curl_multi_fdset()`][12] is called etc.
The libcurl source code generally use the name 'data' for the variable that
points to the Curl_easy.
points to the `Curl_easy`.
When doing multiplexed HTTP/2 transfers, each Curl_easy is associated with
When doing multiplexed HTTP/2 transfers, each `Curl_easy` is associated with
an individual stream, sharing the same connectdata struct. Multiplexing
makes it even more important to keep things associated with the right thing!
@ -901,19 +901,19 @@ for older and later versions as things don't change drastically that often.
the connection can't be kept alive, the connection will be closed after use
and then this struct can be removed from the cache and freed.
Thus, the same Curl_easy can be used multiple times and each time select
Thus, the same `Curl_easy` can be used multiple times and each time select
another connectdata struct to use for the connection. Keep this in mind, as
it is then important to consider if options or choices are based on the
connection or the Curl_easy.
connection or the `Curl_easy`.
Functions in libcurl will assume that connectdata->data points to the
Curl_easy that uses this connection (for the moment).
`Curl_easy` that uses this connection (for the moment).
As a special complexity, some protocols supported by libcurl require a
special disconnect procedure that is more than just shutting down the
socket. It can involve sending one or more commands to the server before
doing so. Since connections are kept in the connection cache after use, the
original Curl_easy may no longer be around when the time comes to shut down
original `Curl_easy` may no longer be around when the time comes to shut down
a particular connection. For this purpose, libcurl holds a special dummy
`closure_handle` Curl_easy in the `Curl_multi` struct to use when needed.
@ -931,34 +931,34 @@ for older and later versions as things don't change drastically that often.
`Curl_multi` is the multi handle struct exposed as "CURLM *" in external APIs.
This struct holds a list of Curl_easy structs that have been added to this
This struct holds a list of `Curl_easy` structs that have been added to this
handle with [`curl_multi_add_handle()`][13]. The start of the list is
->easyp and ->num_easy is a counter of added Curl_easys.
`->easyp` and `->num_easy` is a counter of added `Curl_easy`s.
->msglist is a linked list of messages to send back when
`->msglist` is a linked list of messages to send back when
[`curl_multi_info_read()`][14] is called. Basically a node is added to that
list when an individual Curl_easy's transfer has completed.
list when an individual `Curl_easy`'s transfer has completed.
->hostcache points to the name cache. It is a hash table for looking up name
`->hostcache` points to the name cache. It is a hash table for looking up name
to IP. The nodes have a limited life time in there and this cache is meant
to reduce the time for when the same name is wanted within a short period of
time.
->timetree points to a tree of Curl_easys, sorted by the remaining time
until it should be checked - normally some sort of timeout. Each Curl_easy
`->timetree` points to a tree of `Curl_easy`s, sorted by the remaining time
until it should be checked - normally some sort of timeout. Each `Curl_easy`
has one node in the tree.
->sockhash is a hash table to allow fast lookups of socket descriptor to
which Curl_easy that uses that descriptor. This is necessary for the
`->sockhash` is a hash table to allow fast lookups of socket descriptor to
which `Curl_easy` that uses that descriptor. This is necessary for the
`multi_socket` API.
->conn_cache points to the connection cache. It keeps track of all
`->conn_cache` points to the connection cache. It keeps track of all
connections that are kept after use. The cache has a maximum size.
->closure_handle is described in the 'connectdata' section.
`->closure_handle` is described in the 'connectdata' section.
The libcurl source code generally use the name 'multi' for the variable that
points to the Curl_multi struct.
points to the `Curl_multi` struct.
## Curl_handler
@ -971,40 +971,40 @@ for older and later versions as things don't change drastically that often.
from a single array which is scanned through when a URL is given to libcurl
to work with.
->scheme is the URL scheme name, usually spelled out in uppercase. That's
`->scheme` is the URL scheme name, usually spelled out in uppercase. That's
"HTTP" or "FTP" etc. SSL versions of the protcol need its own `Curl_handler`
setup so HTTPS separate from HTTP.
->setup_connection is called to allow the protocol code to allocate protocol
`->setup_connection` is called to allow the protocol code to allocate protocol
specific data that then gets associated with that Curl_easy for the rest of
this transfer. It gets freed again at the end of the transfer. It will be
called before the 'connectdata' for the transfer has been selected/created.
Most protocols will allocate its private 'struct [PROTOCOL]' here and assign
Curl_easy->req.protop to point to it.
->connect_it allows a protocol to do some specific actions after the TCP
`->connect_it` allows a protocol to do some specific actions after the TCP
connect is done, that can still be considered part of the connection phase.
Some protocols will alter the connectdata->recv[] and connectdata->send[]
function pointers in this function.
Some protocols will alter the `connectdata->recv[]` and
`connectdata->send[]` function pointers in this function.
->connecting is similarly a function that keeps getting called as long as the
protocol considers itself still in the connecting phase.
`->connecting` is similarly a function that keeps getting called as long as
the protocol considers itself still in the connecting phase.
->do_it is the function called to issue the transfer request. What we call
`->do_it` is the function called to issue the transfer request. What we call
the DO action internally. If the DO is not enough and things need to be kept
getting done for the entire DO sequence to complete, ->doing is then usually
also provided. Each protocol that needs to do multiple commands or similar
for do/doing need to implement their own state machines (see SCP, SFTP,
FTP). Some protocols (only FTP and only due to historical reasons) has a
separate piece of the DO state called `DO_MORE`.
getting done for the entire DO sequence to complete, `->doing` is then
usually also provided. Each protocol that needs to do multiple commands or
similar for do/doing need to implement their own state machines (see SCP,
SFTP, FTP). Some protocols (only FTP and only due to historical reasons) has
a separate piece of the DO state called `DO_MORE`.
->doing keeps getting called while issuing the transfer request command(s)
`->doing` keeps getting called while issuing the transfer request command(s)
->done gets called when the transfer is complete and DONE. That's after the
`->done` gets called when the transfer is complete and DONE. That's after the
main data has been transferred.
->do_more gets called during the `DO_MORE` state. The FTP protocol uses this
`->do_more` gets called during the `DO_MORE` state. The FTP protocol uses this
state when setting up the second connection.
->`proto_getsock`
@ -1050,9 +1050,9 @@ for older and later versions as things don't change drastically that often.
## conncache
Is a hash table with connections for later re-use. Each Curl_easy has a
Is a hash table with connections for later re-use. Each `Curl_easy` has a
pointer to its connection cache. Each multi handle sets up a connection
cache that all added Curl_easys share by default.
cache that all added `Curl_easy`s share by default.
## Curl_share
@ -1061,10 +1061,10 @@ for older and later versions as things don't change drastically that often.
The idea is that the struct can have a set of own versions of caches and
pools and then by providing this struct in the `CURLOPT_SHARE` option, those
specific Curl_easys will use the caches/pools that this share handle
specific `Curl_easy`s will use the caches/pools that this share handle
holds.
Then individual Curl_easy structs can be made to share specific things
Then individual `Curl_easy` structs can be made to share specific things
that they otherwise wouldn't, such as cookies.
The `Curl_share` struct can currently hold cookies, DNS cache and the SSL
@ -1073,7 +1073,7 @@ for older and later versions as things don't change drastically that often.
## CookieInfo
This is the main cookie struct. It holds all known cookies and related
information. Each Curl_easy has its own private CookieInfo even when
information. Each `Curl_easy` has its own private CookieInfo even when
they are added to a multi handle. They can be made to share cookies by using
the share API.