From ec68178958818fab236cb59b084c65a60f2d67b1 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Thu, 17 Mar 2022 22:44:11 +0100 Subject: [PATCH] afs.c: Improve documentation of callback_query. It had some language issues and focussed too much on details rather than explaining the big picture. The new text is shorter and should be much easier to understand. --- afs.c | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/afs.c b/afs.c index 522615a3..71067025 100644 --- a/afs.c +++ b/afs.c @@ -90,26 +90,26 @@ static char *current_mop; /* mode or playlist specifier. NULL means dummy mood * extern uint32_t afs_socket_cookie; /** - * Struct to let command handlers execute a callback in afs context. + * Passed from command handlers to afs. * - * Commands that need to change the state of afs can't change the relevant data - * structures directly because commands are executed in a child process, i.e. - * they get their own virtual address space. + * Command handlers cannot change the afs database directly because they run in + * a separate process. The callback query structure circumvents this + * restriction as follows. To instruct the afs process to execute a particular + * function, the command hander writes an instance of this structure to a + * shared memory area, along with the arguments to the callback function. The + * identifier of the shared memory area is transferred to the afs process via + * the command socket. * - * This structure is used by \p send_callback_request() (executed from handler - * context) in order to let the afs process call the specified function. An - * instance of that structure is written to a shared memory area together with - * the arguments to the callback function. The identifier of the shared memory - * area is written to the command socket. + * The afs process reads the shared memory id from the command socket, attaches + * the corresponding area, and calls the callback function whose address is + * stored in the area. * - * The afs process accepts connections on the command socket and reads the - * shared memory id, attaches the corresponding area, calls the given handler to - * perform the desired action and to optionally compute a result. - * - * The result and a \p callback_result structure is then written to another - * shared memory area. The identifier for that area is written to the handler's - * command socket, so that the handler process can read the id, attach the - * shared memory area and use the result. + * The command output, if any, is transferred back to the command handler in + * the same way: The afs process writes the output to a second shared memory + * area together with a fixed size metadata header whose format corresponds to + * the \ref callback_result structure. The identifier of this area is sent back + * to the command handler which attaches the area and forwards the output to + * the remote client. * * \sa \ref struct callback_result. */ -- 2.39.2