mirror of
https://github.com/libevent/libevent.git
synced 2025-01-31 09:12:55 +08:00
For every deprecated function, explain why it is deprecated and what you should call instead.
svn:r1052
This commit is contained in:
parent
52a75f18e1
commit
bdbd5e0e2f
@ -12,8 +12,13 @@
|
||||
/**
|
||||
Obsolete alias for evbuffer_readln(buffer, NULL, EOL_STYLE_ANY).
|
||||
|
||||
@deprecated This function is deprecated because its behavior is not correct
|
||||
for almost any protocol, and also because it's wholly subsumed by
|
||||
evbuffer_readln().
|
||||
|
||||
@param buffer the evbuffer to read from
|
||||
@return pointer to a single line, or NULL if an error occurred
|
||||
|
||||
*/
|
||||
char *evbuffer_readline(struct evbuffer *buffer);
|
||||
|
||||
@ -24,6 +29,13 @@ char *evbuffer_readline(struct evbuffer *buffer);
|
||||
Subsequent calls to evbuffer_setcb() replace callbacks set by previous
|
||||
calls. Setting the callback to NULL removes any previously set callback.
|
||||
|
||||
@deprecated This function is deprecated because it clears all previous
|
||||
callbacks set on the evbuffer, which can cause confusing behavior if
|
||||
multiple parts of the code all want to add their own callbacks on a
|
||||
buffer. Instead, use evbuffer_add(), evbuffer_del(), and
|
||||
evbuffer_setflags() to manage your own evbuffer callbacks without
|
||||
interfering with callbacks set by others.
|
||||
|
||||
@param buffer the evbuffer to be monitored
|
||||
@param cb the callback function to invoke when the evbuffer is modified,
|
||||
or NULL to remove all callbacks.
|
||||
|
@ -56,6 +56,12 @@ extern "C" {
|
||||
calling evdns_resolv_conf_parse() on UNIX and
|
||||
evdns_config_windows_nameservers() on Windows.
|
||||
|
||||
@deprecated This function is deprecated because it always uses the current
|
||||
event base, and is easily confused by multiple calls to event_init(), and
|
||||
so is not safe for multithreaded use. Additionally, it allocates a global
|
||||
structure that only one thread can use. The replacement is
|
||||
evdns_base_new().
|
||||
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see evdns_shutdown()
|
||||
*/
|
||||
@ -68,6 +74,10 @@ int evdns_init(void);
|
||||
an empty result with the error flag set to DNS_ERR_SHUTDOWN. Otherwise,
|
||||
the requests will be silently discarded.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_shutdown().
|
||||
|
||||
@param fail_requests if zero, active requests will be aborted; if non-zero,
|
||||
active requests will return DNS_ERR_SHUTDOWN.
|
||||
@see evdns_init()
|
||||
@ -80,6 +90,10 @@ void evdns_shutdown(int fail_requests);
|
||||
The address should be an IPv4 address in network byte order.
|
||||
The type of address is chosen so that it matches in_addr.s_addr.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_nameserver_add().
|
||||
|
||||
@param address an IP address in network byte order
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see evdns_nameserver_ip_add()
|
||||
@ -94,6 +108,10 @@ int evdns_nameserver_add(unsigned long int address);
|
||||
whether our calls to the various nameserver configuration functions
|
||||
have been successful.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_count_nameservers().
|
||||
|
||||
@return the number of configured nameservers
|
||||
@see evdns_nameserver_add()
|
||||
*/
|
||||
@ -104,6 +122,10 @@ int evdns_count_nameservers(void);
|
||||
|
||||
Resolves will not necessarily be re-attempted until evdns_resume() is called.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_clear_nameservers_and_suspend().
|
||||
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see evdns_resume()
|
||||
*/
|
||||
@ -115,6 +137,10 @@ int evdns_clear_nameservers_and_suspend(void);
|
||||
Re-attempt resolves left in limbo after an earlier call to
|
||||
evdns_clear_nameservers_and_suspend().
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_resume().
|
||||
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see evdns_clear_nameservers_and_suspend()
|
||||
*/
|
||||
@ -126,6 +152,10 @@ int evdns_resume(void);
|
||||
This wraps the evdns_nameserver_add() function by parsing a string as an IP
|
||||
address and adds it as a nameserver.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_nameserver_ip_add().
|
||||
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see evdns_nameserver_add()
|
||||
*/
|
||||
@ -134,6 +164,10 @@ int evdns_nameserver_ip_add(const char *ip_as_string);
|
||||
/**
|
||||
Lookup an A record for a given name.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_resolve_ipv4().
|
||||
|
||||
@param name a DNS hostname
|
||||
@param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
|
||||
@param callback a callback function to invoke when the request is completed
|
||||
@ -161,6 +195,10 @@ struct in6_addr;
|
||||
/**
|
||||
Lookup a PTR record for a given IP address.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_resolve_reverse().
|
||||
|
||||
@param in an IPv4 address
|
||||
@param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
|
||||
@param callback a callback function to invoke when the request is completed
|
||||
@ -173,6 +211,10 @@ int evdns_resolve_reverse(struct in_addr *in, int flags, evdns_callback_type cal
|
||||
/**
|
||||
Lookup a PTR record for a given IPv6 address.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_resolve_reverse_ipv6().
|
||||
|
||||
@param in an IPv6 address
|
||||
@param flags either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query.
|
||||
@param callback a callback function to invoke when the request is completed
|
||||
@ -189,6 +231,10 @@ int evdns_resolve_reverse_ipv6(struct in6_addr *in, int flags, evdns_callback_ty
|
||||
|
||||
ndots, timeout, max-timeouts, max-inflight, and attempts
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_set_option().
|
||||
|
||||
@param option the name of the configuration option to be modified
|
||||
@param val the value to be set
|
||||
@param flags either 0 | DNS_OPTION_SEARCH | DNS_OPTION_MISC
|
||||
@ -210,6 +256,10 @@ int evdns_set_option(const char *option, const char *val, int flags);
|
||||
failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of
|
||||
memory, 5 = short read from file, 6 = no nameservers listed in the file
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_resolv_conf_parse().
|
||||
|
||||
@param flags any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC|
|
||||
DNS_OPTIONS_ALL
|
||||
@param filename the path to the resolv.conf file
|
||||
@ -221,12 +271,20 @@ int evdns_resolv_conf_parse(int flags, const char *const filename);
|
||||
|
||||
/**
|
||||
Clear the list of search domains.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_search_clear().
|
||||
*/
|
||||
void evdns_search_clear(void);
|
||||
|
||||
/**
|
||||
Add a domain to the list of search domains
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_search_add().
|
||||
|
||||
@param domain the domain to be added to the search list
|
||||
*/
|
||||
void evdns_search_add(const char *domain);
|
||||
@ -237,6 +295,10 @@ void evdns_search_add(const char *domain);
|
||||
Sets the number of dots which, when found in a name, causes
|
||||
the first query to be without any search domain.
|
||||
|
||||
@deprecated This function is deprecated because it does not allow the
|
||||
caller to specify which evdns_base it applies to. The recommended
|
||||
function is evdns_base_search_ndots_set().
|
||||
|
||||
@param ndots the new ndots parameter
|
||||
*/
|
||||
void evdns_search_ndots_set(const int ndots);
|
||||
|
@ -103,8 +103,10 @@ const char *event_base_get_method(struct event_base *);
|
||||
/**
|
||||
Gets all event notification mechanisms supported by libevent.
|
||||
|
||||
This functions returns the event mechanism in order preferred
|
||||
by libevent.
|
||||
This functions returns the event mechanism in order preferred by
|
||||
libevent. Note that this list will include all backends that
|
||||
Libevent has compiled-in support for, and will not necessarily check
|
||||
your OS to see whether it has the required resources.
|
||||
|
||||
@return an array with pointers to the names of support methods.
|
||||
The end of the array is indicated by a NULL pointer. If an
|
||||
@ -365,8 +367,9 @@ int event_base_loopbreak(struct event_base *);
|
||||
|
||||
@see event_add(), event_del(), event_once()
|
||||
|
||||
@deprecated event_set() is deprecated. Use event_assign() instead.
|
||||
|
||||
@deprecated event_set() is not recommended for new code, because it requires
|
||||
a subsequent call to event_base_set() to be safe under many circumstances.
|
||||
Use event_assign() or event_new() instead.
|
||||
*/
|
||||
void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t, short, void *), void *);
|
||||
|
||||
@ -388,6 +391,12 @@ void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t,
|
||||
EV_READ, or EV_WRITE. The additional flag EV_PERSIST makes an event_add()
|
||||
persistent until event_del() has been called.
|
||||
|
||||
Note that using event_assign() request that you have already allocated the
|
||||
event struct. Doing so will often require your code to depend on the size
|
||||
of the structure, and will create possible incompatibility with future
|
||||
versions of libevent. If this seems like a bad idea to you, use event_new()
|
||||
and event_free() instead.
|
||||
|
||||
@param ev an event struct to be modified
|
||||
@param base the event base to which ev should be attached.
|
||||
@param fd the file descriptor to be monitored
|
||||
@ -415,7 +424,7 @@ struct event *event_new(struct event_base *, evutil_socket_t, short, void (*)(ev
|
||||
void event_free(struct event *);
|
||||
|
||||
/**
|
||||
Schedule a one-time event (threadsafe variant)
|
||||
Schedule a one-time event
|
||||
|
||||
The function event_base_once() is similar to event_set(). However, it
|
||||
schedules a callback to be called exactly once and does not require the
|
||||
|
@ -62,6 +62,10 @@ extern "C" {
|
||||
used. Sets the current_base global representing the default base for
|
||||
events that have no base associated with them.
|
||||
|
||||
@deprecated This function is deprecated because it relaces the "current"
|
||||
event_base, and is totally unsafe for multithreaded use. The replacement
|
||||
is event_base_new().
|
||||
|
||||
@see event_base_set(), event_base_new()
|
||||
*/
|
||||
struct event_base *event_init(void);
|
||||
@ -73,6 +77,10 @@ struct event_base *event_init(void);
|
||||
event_dispatch(). This function only returns on error, and should
|
||||
replace the event core of the application program.
|
||||
|
||||
@deprecated This function is deprecated because it is easily confused by
|
||||
multiple calls to event_init(), and because it is not safe for
|
||||
multithreaded use. The replacement is event_base_dispatch().
|
||||
|
||||
@see event_base_dispatch()
|
||||
*/
|
||||
int event_dispatch(void);
|
||||
@ -82,10 +90,14 @@ int event_dispatch(void);
|
||||
|
||||
This is a more flexible version of event_dispatch().
|
||||
|
||||
@deprecated This function is deprecated because it uses the event base from
|
||||
the last call to event_init, and is therefore not safe for multithreaded
|
||||
use. The replacement is event_base_loop().
|
||||
|
||||
@param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
|
||||
@return 0 if successful, -1 if an error occurred, or 1 if no events were
|
||||
registered.
|
||||
@see event_loopexit(), event_base_loop()
|
||||
@see event_base_loopexit(), event_base_loop()
|
||||
*/
|
||||
int event_loop(int);
|
||||
|
||||
@ -99,6 +111,10 @@ int event_loop(int);
|
||||
|
||||
Subsequent invocations of event_loop() will proceed normally.
|
||||
|
||||
@deprecated This function is deprecated because it is easily confused by
|
||||
multiple calls to event_init(), and because it is not safe for
|
||||
multithreaded use. The replacement is event_base_loopexit().
|
||||
|
||||
@param tv the amount of time after which the loop should terminate.
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see event_loop(), event_base_loop(), event_base_loopexit()
|
||||
@ -115,6 +131,10 @@ int event_loopexit(const struct timeval *);
|
||||
|
||||
Subsequent invocations of event_loop() will proceed normally.
|
||||
|
||||
@deprecated This function is deprecated because it is easily confused by
|
||||
multiple calls to event_init(), and because it is not safe for
|
||||
multithreaded use. The replacement is event_base_loopbreak().
|
||||
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see event_base_loopbreak(), event_loopexit()
|
||||
*/
|
||||
@ -127,6 +147,10 @@ int event_loopbreak(void);
|
||||
a callback to be called exactly once and does not require the caller to
|
||||
prepare an event structure.
|
||||
|
||||
@deprecated This function is deprecated because it is easily confused by
|
||||
multiple calls to event_init(), and because it is not safe for
|
||||
multithreaded use. The replacement is event_base_once().
|
||||
|
||||
@param fd a file descriptor to monitor
|
||||
@param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ |
|
||||
EV_WRITE
|
||||
@ -146,6 +170,10 @@ int event_once(evutil_socket_t , short,
|
||||
Get the kernel event notification mechanism used by libevent.
|
||||
|
||||
@return a string identifying the kernel event mechanism (kqueue, epoll, etc.)
|
||||
|
||||
@deprecated This function is deprecated because it is easily confused by
|
||||
multiple calls to event_init(), and because it is not safe for
|
||||
multithreaded use. The replacement is event_base_get_method().
|
||||
*/
|
||||
const char *event_get_method(void);
|
||||
|
||||
@ -165,6 +193,10 @@ const char *event_get_method(void);
|
||||
used to assign a priority to an event. By default, libevent assigns the
|
||||
middle priority to all events unless their priority is explicitly set.
|
||||
|
||||
@deprecated This function is deprecated because it is easily confused by
|
||||
multiple calls to event_init(), and because it is not safe for
|
||||
multithreaded use. The replacement is event_base_priority_init().
|
||||
|
||||
@param npriorities the maximum number of priorities
|
||||
@return 0 if successful, or -1 if an error occurred
|
||||
@see event_base_priority_init(), event_priority_set()
|
||||
@ -178,6 +210,9 @@ int event_priority_init(int);
|
||||
*
|
||||
* @param ev the event struct to be disabled
|
||||
* @param tv the timeout value, in seconds
|
||||
*
|
||||
* @deprecated This macro is deprecated because its naming is inconsistent.
|
||||
* The recommend macro is evtimer_add().
|
||||
*/
|
||||
#define timeout_add(ev, tv) event_add(ev, tv)
|
||||
|
||||
@ -188,6 +223,9 @@ int event_priority_init(int);
|
||||
* @param ev the event struct to be defined
|
||||
* @param cb the callback to be invoked when the timeout expires
|
||||
* @param arg the argument to be passed to the callback
|
||||
*
|
||||
* @deprecated This macro is deprecated because its naming is inconsistent.
|
||||
* The recommend macro is evtimer_set().
|
||||
*/
|
||||
#define timeout_set(ev, cb, arg) event_set(ev, -1, 0, cb, arg)
|
||||
|
||||
@ -195,21 +233,60 @@ int event_priority_init(int);
|
||||
* Disable a timeout event.
|
||||
*
|
||||
* @param ev the timeout event to be disabled
|
||||
*
|
||||
* @deprecated This macro is deprecated because its naming is inconsistent.
|
||||
* The recommend macro is evtimer_del().
|
||||
*/
|
||||
#define timeout_del(ev) event_del(ev)
|
||||
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evtimer_pending().
|
||||
*/
|
||||
#define timeout_pending(ev, tv) event_pending(ev, EV_TIMEOUT, tv)
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evtimer_initialized().
|
||||
*/
|
||||
#define timeout_initialized(ev) _event_initialized((ev), 0)
|
||||
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evsignal_add().
|
||||
*/
|
||||
#define signal_add(ev, tv) event_add(ev, tv)
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evsignal_set().
|
||||
*/
|
||||
#define signal_set(ev, x, cb, arg) \
|
||||
event_set(ev, x, EV_SIGNAL|EV_PERSIST, cb, arg)
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evsignal_assign().
|
||||
*/
|
||||
#define signal_assign(ev, b, x, cb, arg) \
|
||||
event_assign(ev, b, x, EV_SIGNAL|EV_PERSIST, cb, arg)
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evsignal_new().
|
||||
*/
|
||||
#define signal_new(b, x, cb, arg) \
|
||||
event_new(b, x, EV_SIGNAL|EV_PERSIST, cb, arg)
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evsignal_del().
|
||||
*/
|
||||
#define signal_del(ev) event_del(ev)
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evsignal_pending().
|
||||
*/
|
||||
#define signal_pending(ev, tv) event_pending(ev, EV_SIGNAL, tv)
|
||||
/**
|
||||
@deprecated This macro is deprecated because its naming is inconsistent.
|
||||
The recommend macro is evsignal_initialized().
|
||||
*/
|
||||
#define signal_initialized(ev) _event_initialized((ev), 0)
|
||||
|
||||
#ifdef __cplusplus
|
||||
|
@ -58,7 +58,7 @@ extern "C" {
|
||||
/**
|
||||
* Start an HTTP server on the specified address and port
|
||||
*
|
||||
* DEPRECATED: it does not allow an event base to be specified
|
||||
* @deprecated It does not allow an event base to be specified
|
||||
*
|
||||
* @param address the address to which the HTTP server should be bound
|
||||
* @param port the port number on which the HTTP server should listen
|
||||
@ -70,6 +70,8 @@ struct evhttp *evhttp_start(const char *address, unsigned short port);
|
||||
* A connection object that can be used to for making HTTP requests. The
|
||||
* connection object tries to establish the connection when it is given an
|
||||
* http request object.
|
||||
*
|
||||
* @deprecated It does not allow an event base to be specified
|
||||
*/
|
||||
struct evhttp_connection *evhttp_connection_new(
|
||||
const char *address, unsigned short port);
|
||||
@ -77,6 +79,8 @@ struct evhttp_connection *evhttp_connection_new(
|
||||
/**
|
||||
* Associates an event base with the connection - can only be called
|
||||
* on a freshly created connection object that has not been used yet.
|
||||
*
|
||||
* @deprecated XXXX Why?
|
||||
*/
|
||||
void evhttp_connection_set_base(struct evhttp_connection *evcon,
|
||||
struct event_base *base);
|
||||
|
Loading…
x
Reference in New Issue
Block a user