rainlance
/
c-ares
mirror of https://frontier.innolan.net/rainlance/c-ares.git
1
0
Fork 0
Code Releases Activity

library init: documentation update 

This commit updates the documentation of ares_library_init() and
ares_library_cleanup() with regard to the newly introduced reference
counting of initializations and deinitializations.
This commit is contained in:
Alexander Klauer 2013-03-18 09:23:30 +01:00 committed by Daniel Stenberg
parent 2e0c3076e5
commit 9a92b80191
2 changed files with 28 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
ares_library_cleanup.3
View File

@ -31,11 +31,19 @@ The
.B ares_library_cleanup .B ares_library_cleanup
function uninitializes the c-ares library, freeing all resources function uninitializes the c-ares library, freeing all resources
previously acquired by \fIares_library_init(3)\fP when the library previously acquired by \fIares_library_init(3)\fP when the library
was initialized. was initialized, provided there was only one single previous call to
\fIares_library_init(3)\fP. If there was more than one previous call to
\fIares_library_init(3)\fP, this function uninitializes the c-ares
library only if it is the call matching the call to
\fIares_library_init(3)\fP which initialized the library
(usually the very first call to \fIares_library_init(3)\fP).
Other calls to \fIares_library_cleanup(3)\fP have no effect other than
decrementing an internal counter.
.PP .PP
This function must be called when the program using c-ares will This function must be called when the program using c-ares will
no longer need any c-ares function. Once the program has called no longer need any c-ares function. Once the program has called
\fIares_library_cleanup(3)\fP it shall not make any further call to any \fIares_library_cleanup(3)\fP sufficiently often such that the
library is uninitialised, it shall not make any further call to any
c-ares function. c-ares function.
.PP .PP
This function does not cancel any pending c-ares lookups or requests This function does not cancel any pending c-ares lookups or requests
@ -54,7 +62,12 @@ the DllMain function. Doing so will produce deadlocks and other problems.
.SH AVAILABILITY .SH AVAILABILITY
This function was first introduced in c-ares version 1.7.0 along with the This function was first introduced in c-ares version 1.7.0 along with the
definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_CLEANUP\fP as an definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_CLEANUP\fP as an
indication of the availability of this function. indication of the availability of this function. Reference counting in
\fIares_library_init()\fP and \fIares_library_cleanup()\fP, which requires
calls to the former function to match calls to the latter, is present since
c-ares version 1.10.0.
Earlier versions would deinitialize the library on the first call
to \fIares_library_cleanup()\fP.
.PP .PP
Since the introduction of this function, it is absolutely mandatory to call it Since the introduction of this function, it is absolutely mandatory to call it
for any Win32/64 program using c-ares. for any Win32/64 program using c-ares.

18
ares_library_init.3
View File

@ -33,13 +33,15 @@ function performs initializations internally required by the c-ares
library that must take place before any other function provided by library that must take place before any other function provided by
c-ares can be used in a program. c-ares can be used in a program.
.PP .PP
This function must be called one time within the life of a program, This function must be called at least once within the life of a program,
before the program actually executes any other c-ares library function. before the program actually executes any other c-ares library function.
Initializations done by this function remain effective until a Initializations done by this function remain effective until a number of
call to \fIares_library_cleanup(3)\fP is performed. calls to \fIares_library_cleanup(3)\fP equal to the number of calls to
this function are performed.
.PP .PP
Successive calls to this function do nothing, only the first call done Successive calls to this function do nothing further, only the first
when c-ares is in an uninitialized state is actually effective. call done when c-ares is in an uninitialized state is actually
effective.
.PP .PP
The The
.I flags .I flags
@ -77,7 +79,11 @@ non-zero error number will be returned to indicate the error. Except for
.SH AVAILABILITY .SH AVAILABILITY
This function was first introduced in c-ares version 1.7.0 along with the This function was first introduced in c-ares version 1.7.0 along with the
definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_INIT\fP as an definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_INIT\fP as an
indication of the availability of this function. indication of the availability of this function. Its recursive behavior,
which requires a matching number of calls to \fIares_library_cleanup()\fP
in order to deinitialize the library, is present since c-ares version
1.10.0. Earlier versions would deinitialize the library on the first call
to \fIares_library_cleanup()\fP.
.PP .PP
Since the introduction of this function it is absolutely mandatory to Since the introduction of this function it is absolutely mandatory to
call it for any Win32/64 program using c-ares. call it for any Win32/64 program using c-ares.