From fcc9b0efe1accdb0edcb3143a8e15782e69383db Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Sun, 14 Aug 2005 02:33:41 +0000 Subject: * doxygen documentation updates * make AvahiPoll objects const * make poll() functions pluggable in AvahiSimplePoll git-svn-id: file:///home/lennart/svn/public/avahi/trunk@314 941a03a8-eaeb-0310-b9a0-b1bbd8fe43fe --- avahi-common/alternative.h | 12 +++++++---- avahi-common/gccmacro.h | 7 +++++++ avahi-common/simple-watch.c | 17 ++++++++++++---- avahi-common/simple-watch.h | 35 +++++++++++++++++++++++++++++++- avahi-common/watch-test.c | 2 +- avahi-common/watch.h | 49 ++++++++++++++++++++++++++++++++++++--------- 6 files changed, 103 insertions(+), 19 deletions(-) (limited to 'avahi-common') diff --git a/avahi-common/alternative.h b/avahi-common/alternative.h index 3d7b2fe..fa45d96 100644 --- a/avahi-common/alternative.h +++ b/avahi-common/alternative.h @@ -22,24 +22,28 @@ USA. ***/ -#include - /** \file alternative.h Functions to find alternative names for hosts and services in the case of name collision */ +#include + +#ifndef DOXYGEN_SHOULD_SKIP_THIS AVAHI_C_DECL_BEGIN +#endif /** Find an alternative for the specified host name. If called with an * original host name, "2" is appended, Afterwards the number is * increased on each call. (i.e. "foo" becomes "foo2" becomes "foo3" - * and so on.) g_free() the result. */ + * and so on.) avahi_free() the result. */ char *avahi_alternative_host_name(const char *s); /** Find an alternative for the specified service name. If called with an original service name, " #2" is appended. Afterwards the number is increased on each call (i.e. "foo" becomes "foo #2" becomes - "foo #3" and so on.) g_free() the result. */ + "foo #3" and so on.) avahi_free() the result. */ char *avahi_alternative_service_name(const char *s); +#ifndef DOXYGEN_SHOULD_SKIP_THIS AVAHI_C_DECL_END +#endif #endif diff --git a/avahi-common/gccmacro.h b/avahi-common/gccmacro.h index 42fb153..2ac6c1d 100644 --- a/avahi-common/gccmacro.h +++ b/avahi-common/gccmacro.h @@ -22,9 +22,12 @@ USA. ***/ +/** \file gccmacro.h Defines some macros for GCC extensions */ + #ifdef __GNUC__ #define AVAHI_GCC_SENTINEL __attribute__ ((sentinel)) #else +/** Macro for usage of GCC's sentinel compilation warnings */ #define AVAHI_GCC_SENTINEL #endif @@ -35,12 +38,16 @@ #define AVAHI_GCC_PRINTF_ATTR(a,b) #endif +/** Same as AVAHI_GCC_PRINTF_ATTR but hard coded to arguments 1 and 2 */ #define AVAHI_GCC_PRINTF_ATTR12 AVAHI_GCC_PRINTF_ATTR(1,2) + +/** Same as AVAHI_GCC_PRINTF_ATTR but hard coded to arguments 2 and 3 */ #define AVAHI_GCC_PRINTF_ATTR23 AVAHI_GCC_PRINTF_ATTR(2,3) #ifdef __GNUC__ #define AVAHI_GCC_NORETURN __attribute__((noreturn)) #else +/** Macro for no-return functions */ #define AVAHI_GCC_NORETURN #endif diff --git a/avahi-common/simple-watch.c b/avahi-common/simple-watch.c index 3caf371..5e03fe4 100644 --- a/avahi-common/simple-watch.c +++ b/avahi-common/simple-watch.c @@ -46,6 +46,7 @@ struct AvahiWatch { struct AvahiSimplePoll { AvahiPoll api; + AvahiPollFunc poll_func; struct pollfd* pollfds; int n_pollfds, max_pollfds, rebuild_pollfds; @@ -62,7 +63,7 @@ struct AvahiSimplePoll { AVAHI_LLIST_HEAD(AvahiWatch, watches); }; -static AvahiWatch* watch_new(AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata) { +static AvahiWatch* watch_new(const AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata) { AvahiWatch *w; AvahiSimplePoll *s; @@ -142,7 +143,7 @@ static void watch_free(AvahiWatch *w) { w->simple_poll->req_cleanup = 1; } -static void set_wakeup(AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata) { +static void set_wakeup(const AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata) { AvahiSimplePoll *s; assert(api); @@ -207,6 +208,8 @@ AvahiSimplePoll *avahi_simple_poll_new(void) { s->n_watches = 0; s->req_cleanup = 0; + avahi_simple_poll_set_func(s, NULL); + AVAHI_LLIST_HEAD_INIT(AvahiWatch, s->watches); return s; @@ -315,7 +318,7 @@ int avahi_simple_poll_iterate(AvahiSimplePoll *s, int timeout) { timeout = t; } - if ((r = poll(s->pollfds, s->n_pollfds, timeout)) < 0) + if ((r = s->poll_func(s->pollfds, s->n_pollfds, timeout)) < 0) return -1; /* Check whether the wakeup time has been reached now */ @@ -359,8 +362,14 @@ void avahi_simple_poll_quit(AvahiSimplePoll *w) { w->quit = 1; } -AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s) { +const AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s) { assert(s); return &s->api; } + +void avahi_simple_poll_set_func(AvahiSimplePoll *s, AvahiPollFunc func) { + assert(s); + + s->poll_func = func ? func : (AvahiPollFunc) poll; +} diff --git a/avahi-common/simple-watch.h b/avahi-common/simple-watch.h index 127ddc5..c8234f2 100644 --- a/avahi-common/simple-watch.h +++ b/avahi-common/simple-watch.h @@ -22,23 +22,56 @@ USA. ***/ +/** \file simple-watch.h Simple poll() based main loop implementation */ + +#include #include #include "watch.h" +#ifndef DOXYGEN_SHOULD_SKIP_THIS AVAHI_C_DECL_BEGIN +#endif +/** A main loop object. Main loops of this type aren't very flexible + * since they only support a single wakeup type. Nevertheless it + * should suffice for small test and example applications. */ typedef struct AvahiSimplePoll AvahiSimplePoll; +/** Create a new main loop object */ AvahiSimplePoll *avahi_simple_poll_new(void); + +/** Free a main loop object */ void avahi_simple_poll_free(AvahiSimplePoll *s); -AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s); +/** Return the abstracted poll API object for this main loop + * object. The is will return the same pointer each time it is + * called. */ +const AvahiPoll* avahi_simple_poll_get(AvahiSimplePoll *s); +/** Run a single main loop iteration of this main loop. If sleep_time +is < 0 this will block until any of the registered events happens, +then it will execute the attached callback function. If sleep_time is +0 the routine just checks if any event is pending. If yes the attached +callback function is called, otherwise the function returns +immediately. If sleep_time > 0 the function will block for at most the +specified time in msecs. Returns -1 on error, 0 on success and 1 if a +quit request has been scheduled. Usually this function should be called +in a loop until it returns a non-zero value*/ int avahi_simple_poll_iterate(AvahiSimplePoll *s, int sleep_time); +/** Request that the main loop quits. If this is called the next + call to avahi_simple_poll_iterate() will return 1 */ void avahi_simple_poll_quit(AvahiSimplePoll *s); +/** Prototype for a poll() type function */ +typedef int (*AvahiPollFunc)(struct pollfd *ufds, unsigned int nfds, int timeout); + +/** Replace the internally used poll() function. By default the system's poll() will be used */ +void avahi_simple_poll_set_func(AvahiSimplePoll *s, AvahiPollFunc func); + +#ifndef DOXYGEN_SHOULD_SKIP_THIS AVAHI_C_DECL_END +#endif #endif diff --git a/avahi-common/watch-test.c b/avahi-common/watch-test.c index af46805..a9e3e02 100644 --- a/avahi-common/watch-test.c +++ b/avahi-common/watch-test.c @@ -33,7 +33,7 @@ #include "simple-watch.h" #include "timeval.h" -static AvahiPoll *api = NULL; +static const AvahiPoll *api = NULL; static AvahiSimplePoll *simple_poll = NULL; static void callback(AvahiWatch *w, int fd, AvahiWatchEvent event, void *userdata) { diff --git a/avahi-common/watch.h b/avahi-common/watch.h index 70dedb7..75f53b3 100644 --- a/avahi-common/watch.h +++ b/avahi-common/watch.h @@ -22,37 +22,68 @@ USA. ***/ +/** \file watch.h Simplistic main loop abstraction */ + #include #include #include "timeval.h" +#ifndef DOXYGEN_SHOULD_SKIP_THIS AVAHI_C_DECL_BEGIN +#endif +/** An I/O watch object */ typedef struct AvahiWatch AvahiWatch; + +/** An event polling abstraction object */ typedef struct AvahiPoll AvahiPoll; +/** Type of watch events */ typedef enum { - AVAHI_WATCH_IN = POLLIN, - AVAHI_WATCH_OUT = POLLOUT, - AVAHI_WATCH_ERR = POLLERR, - AVAHI_WATCH_HUP = POLLHUP + AVAHI_WATCH_IN = POLLIN, /** Input event */ + AVAHI_WATCH_OUT = POLLOUT, /** Output event */ + AVAHI_WATCH_ERR = POLLERR, /** Error event */ + AVAHI_WATCH_HUP = POLLHUP /** Hangup event */ } AvahiWatchEvent; +/** Called whenever an I/O event happens on an I/O watch */ typedef void (*AvahiWatchCallback)(AvahiWatch *w, int fd, AvahiWatchEvent event, void *userdata); + +/** Called when the wakeup time is reached */ typedef void (*AvahiWakeupCallback)(AvahiPoll *api, void *userdata); +/** Defines an abstracted event polling API. This may be used to + connect Avahi to other main loops. This is losely based on Unix + poll(2). A consumer will call watch_new() for all file descriptors it + wants to listen for events on. In addition he can call set_wakeup() + to define a single wakeup time.*/ struct AvahiPoll { - void* userdata; - - AvahiWatch* (*watch_new)(AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata); + + /** Some abstract user data usable by the implementor of the API */ + void* userdata; + + /** Create a new watch for the specified file descriptor and for + * the specified events. The API will call the callback function + * whenever any of the events happens. */ + AvahiWatch* (*watch_new)(const AvahiPoll *api, int fd, AvahiWatchEvent event, AvahiWatchCallback callback, void *userdata); + + /** Update the events to wait for. */ void (*watch_update)(AvahiWatch *w, AvahiWatchEvent event); + + /** Free a watch */ void (*watch_free)(AvahiWatch *w); - - void (*set_wakeup)(AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata); + + /** Set a wakeup time for the polling loop. The API will call the + callback function when the absolute time *tv is reached. If *tv is + NULL, the callback will be called in the next main loop + iteration. If callback is NULL the wakeup time is disabled. */ + void (*set_wakeup)(const AvahiPoll *api, const struct timeval *tv, AvahiWakeupCallback callback, void *userdata); }; +#ifndef DOXYGEN_SHOULD_SKIP_THIS AVAHI_C_DECL_END +#endif #endif -- cgit