For every deprecated function, explain why it is deprecated and what you should call instead.

svn:r1052
This commit is contained in:
Nick Mathewson 2009-01-26 17:09:37 +00:00
parent 52a75f18e1
commit bdbd5e0e2f
5 changed files with 171 additions and 7 deletions

View File

@ -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.

View File

@ -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);

View File

@ -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

View File

@ -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

View File

@ -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);