From 7ba6e107eb38c5ceb6f66aac21ad6a5a3afa49ad Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Tue, 25 Mar 2008 01:19:21 +0100 Subject: [PATCH] Update doxygen documentation. --- afs.c | 65 ++++++++++++++++++++++++++++++++++++++++++++---------- afs.h | 14 +++++++++--- aft.c | 2 +- mood.c | 2 +- playlist.c | 2 +- string.h | 2 +- 6 files changed, 68 insertions(+), 19 deletions(-) diff --git a/afs.c b/afs.c index 2260344e..d7c1ecfd 100644 --- a/afs.c +++ b/afs.c @@ -145,11 +145,20 @@ struct callback_result { * * \param f The function to be called. * \param query Pointer to arbitrary data for the callback. - * \param result Callback result will be stored here. + * \param result_handler Called for each shm area sent by the callback. + * \param private_result_data Passed verbatim to \a result_handler. * - * This function creates a shared memory area, copies the buffer pointed to by - * \a query to that area and notifies the afs process that \a f should be - * called ASAP. + * This function creates a socket for communication with the afs process and a + * shared memory area (sma) to which the buffer pointed to by \a query is + * copied. It then notifies the afs process that the callback function \a f + * should be executed by sending the shared memory identifier (shmid) to the + * socket. + + * If the callback produces a result, it sends any number of shared memory + * identifiers back via the socket. For each such identifier received, \a + * result_handler is called. The contents of the sma identified by the received + * shmid are passed to that function as an osl object. The private_result_data + * pointer is passed as the second argument to \a result_handler. * * \return Negative, on errors, the return value of the callback function * otherwise. @@ -245,7 +254,8 @@ out: * \param argc Argument count. * \param argv Standard argument vector. * \param f The callback function. - * \param result The result of the query is stored here. + * \param result_handler See \ref send_callback_request. + * \param private_result_data See \ref send_callback_request. * * Some commands have a couple of options that are parsed in child context for * syntactic correctness and are stored in a special options structure for that @@ -287,7 +297,8 @@ int send_option_arg_callback_request(struct osl_object *options, * \param argc The same meaning as in send_option_arg_callback_request(). * \param argv The same meaning as in send_option_arg_callback_request(). * \param f The same meaning as in send_option_arg_callback_request(). - * \param result The same meaning as in send_option_arg_callback_request(). + * \param result_handler See \ref send_callback_request. + * \param private_result_data See \ref send_callback_request. * * This is similar to send_option_arg_callback_request(), but no options buffer * is passed to the parent process. @@ -407,13 +418,15 @@ static int fd2buf(int fd, unsigned max_size, struct osl_object *obj) * \param arg_obj Pointer to the arguments to \a f. * \param f The callback function. * \param max_len Don't read more than that many bytes from stdin. - * \param result The result of the query is stored here. + * \param result_handler See \ref send_callback_request. + * \param private_result_data See \ref send_callback_request. * * This function is used by commands that wish to let para_server store * arbitrary data specified by the user (for instance the add_blob family of * commands). First, at most \a max_len bytes are read from \a fd, the result * is concatenated with the buffer given by \a arg_obj, and the combined buffer - * is made available to the parent process via shared memory. + * is made available to the afs process via the callback method. See \ref + * send_callback_request for details. * * \return Negative on errors, the return value of the underlying call to * send_callback_request() otherwise. @@ -612,9 +625,19 @@ out: free(pb.buf); } -int send_result(struct osl_object *result, void *private_result_data) +/** + * Result handler for sending data to the para_client process. + * + * \param result The data to be sent. + * \param fd_ptr Pointer to the file descriptor. + * + * \return The return value of the underlying call to send_bin_buffer(). + * + * \sa \ref callback_result_handler. + */ +int send_result(struct osl_object *result, void *fd_ptr) { - int fd = *(int *)private_result_data; + int fd = *(int *)fd_ptr; if (!result->size) return 1; return send_bin_buffer(fd, result->data, result->size); @@ -805,9 +828,27 @@ static void command_pre_select(struct sched *s, struct task *t) t->ret = 1; } -int pass_buffer_as_shm(char *buf, size_t size, void *private_data) +/** + * Send data as shared memory to a file descriptor. + * + * \param buf The buffer holding the data to be sent. + * \param size The size of \a buf. + * \param fd_ptr A pointer to the file descriptor. + * + * This function is used as the \a max_size handler in a \ref para_buffer + * structure. If used this way, it is called by \ref para_printf() whenever + * the buffer passed to para_printf() is about to exceed its maximal size. + * + * This function creates a shared memory area large enough to hold + * the content given by \a buf and \a size and sends the identifier + * of this area to the file descriptor given by \a fd_ptr. + * + * \return Zero if \a buf is \p NULL or \a size is zero. Negative on errors, + * and positive on success. + */ +int pass_buffer_as_shm(char *buf, size_t size, void *fd_ptr) { - int ret, shmid, fd = *(int *)private_data; + int ret, shmid, fd = *(int *)fd_ptr; void *shm; struct callback_result *cr; diff --git a/afs.h b/afs.h index ad9bfc86..d01f0cfb 100644 --- a/afs.h +++ b/afs.h @@ -159,7 +159,7 @@ struct pattern_match_data { int (*action)(struct osl_table *table, struct osl_row *row, const char *name, void *data); }; -/* afs */ + /** * Afs command handlers run as a process which is not related to the afs * process, i.e. they can not change the address space of afs directly. @@ -169,9 +169,17 @@ struct pattern_match_data { * \sa send_callback_request(). */ typedef void callback_function(int fd, const struct osl_object *); + +/** + * Callbacks send chunks to data back to the command handler. Pointers to + * this type of function are used by \ref send_callback_request and friends + * to deal with the data in the command handler process. + * + * \sa \ref send_callback_request(). + */ typedef int callback_result_handler(struct osl_object *result, void *private); -int send_result(struct osl_object *result, void *private_result_data); -int pass_buffer_as_shm(char *buf, size_t size, void *private_data); +int send_result(struct osl_object *result, void *fd_ptr); +int pass_buffer_as_shm(char *buf, size_t size, void *fd_ptr); __noreturn void afs_init(uint32_t cookie, int socket_fd); void afs_event(enum afs_events event, struct para_buffer *pb, diff --git a/aft.c b/aft.c index 0ffacbe4..f6cfddf9 100644 --- a/aft.c +++ b/aft.c @@ -2378,8 +2378,8 @@ static int check_audio_file(struct osl_row *row, void *data) /** * Check the audio file table for inconsistencies. * + * \param fd The afs socket. * \param query Unused. - * \param result Contains message string upon return. * * This function always succeeds. * diff --git a/mood.c b/mood.c index 590a68fb..40f3cacb 100644 --- a/mood.c +++ b/mood.c @@ -561,8 +561,8 @@ out: /** * Check all moods for syntax errors. * + * \param fd The afs socket. * \param query Unused. - * \param result: Contains check messages. */ void mood_check_callback(int fd, __a_unused const struct osl_object *query) { diff --git a/playlist.c b/playlist.c index 7a912bad..171ebab5 100644 --- a/playlist.c +++ b/playlist.c @@ -120,8 +120,8 @@ static int check_playlist(struct osl_row *row, void *data) /** * Check the playlist table for inconsistencies. * + * \param fd The afs socket. * \param query Unused. - * \param result Contains messages about inconsistencies. * * \return The return value of the underlying call to osl_rbtree_loop(). */ diff --git a/string.h b/string.h index c01d6196..561ff4e8 100644 --- a/string.h +++ b/string.h @@ -18,7 +18,7 @@ struct para_buffer { size_t offset; /** * If an attempt to print into this buffer is made that would need to - * grow \buf to a size larger than \a max_size, then this function is + * grow \a buf to a size larger than \a max_size, then this function is * called. */ int (*max_size_handler)(char *buf, size_t size, void *private_data); -- 2.39.5