From bdbd5e0e2fda62f2f0d277867319d470d096b096 Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Mon, 26 Jan 2009 17:09:37 +0000 Subject: [PATCH] For every deprecated function, explain why it is deprecated and what you should call instead. svn:r1052 --- include/event2/buffer_compat.h | 12 ++++++ include/event2/dns_compat.h | 62 ++++++++++++++++++++++++++ include/event2/event.h | 19 +++++--- include/event2/event_compat.h | 79 +++++++++++++++++++++++++++++++++- include/event2/http_compat.h | 6 ++- 5 files changed, 171 insertions(+), 7 deletions(-) diff --git a/include/event2/buffer_compat.h b/include/event2/buffer_compat.h index 8c82a0a6..6f1aad9e 100644 --- a/include/event2/buffer_compat.h +++ b/include/event2/buffer_compat.h @@ -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. diff --git a/include/event2/dns_compat.h b/include/event2/dns_compat.h index 4d58231c..105d65c4 100644 --- a/include/event2/dns_compat.h +++ b/include/event2/dns_compat.h @@ -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); diff --git a/include/event2/event.h b/include/event2/event.h index 784b4510..0122bce2 100644 --- a/include/event2/event.h +++ b/include/event2/event.h @@ -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 diff --git a/include/event2/event_compat.h b/include/event2/event_compat.h index 1b506313..ad81eb21 100644 --- a/include/event2/event_compat.h +++ b/include/event2/event_compat.h @@ -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 diff --git a/include/event2/http_compat.h b/include/event2/http_compat.h index 93135e60..ec1088eb 100644 --- a/include/event2/http_compat.h +++ b/include/event2/http_compat.h @@ -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); -- 2.40.0