From 742c8b3f79a59278ced71e1855da1846b157b494 Mon Sep 17 00:00:00 2001 From: Andre Noll Date: Thu, 7 Oct 2021 22:16:09 +0200 Subject: [PATCH] Misc documentation cleanups related to select(). Assorted comment cleanups which avoid to talk about select(2) and fd sets. No code changes. --- alsa_write.c | 2 +- audiod_command.c | 4 ++-- check_wav.c | 10 +++++----- send.h | 18 ++---------------- signal.c | 2 +- signal.h | 15 +++++++-------- vss.c | 4 ++-- 7 files changed, 20 insertions(+), 35 deletions(-) diff --git a/alsa_write.c b/alsa_write.c index 19223344..b13697ab 100644 --- a/alsa_write.c +++ b/alsa_write.c @@ -48,7 +48,7 @@ struct private_alsa_write_data { /* time until buffer underrun occurs, in milliseconds */ unsigned buffer_time; struct timeval drain_barrier; - /* File descriptor for select(). */ + /* File descriptor to monitor for reading. */ int poll_fd; }; diff --git a/audiod_command.c b/audiod_command.c index 677abe34..795e2ac8 100644 --- a/audiod_command.c +++ b/audiod_command.c @@ -361,8 +361,8 @@ EXPORT_AUDIOD_CMD_HANDLER(version) * * \param accept_fd The fd to accept connections on. * - * This is called in each iteration of the select loop. If there is an incoming - * connection on \a accept_fd, this function reads the command sent by the peer, + * This is called in each iteration of the main loop of the scheduler. If there + * is an incoming connection, the function reads the command sent by the peer, * checks the connecting user's permissions by using unix socket credentials * (if supported by the OS) and calls the corresponding command handler if * permissions are OK. diff --git a/check_wav.c b/check_wav.c index 89ebdacc..074ad8fe 100644 --- a/check_wav.c +++ b/check_wav.c @@ -39,13 +39,13 @@ struct check_wav_context { }; /** - * Set select timeout according to the given context. + * Request a minimal timeout if not idle. * - * \param s Contains the timeval that should be set. - * \param cwc Contains a pointer to the buffer tree node. + * \param s The scheduler instance. + * \param cwc The buffer tree node is derived from this. * - * This requests a minimal timeout from the scheduler if btrn of \a cwc is not - * idle. + * If no data is available and the buffer tree node is not in error state, the + * function does nothing. */ void check_wav_pre_select(struct sched *s, struct check_wav_context *cwc) { diff --git a/send.h b/send.h index 1d9db37e..25a1103d 100644 --- a/send.h +++ b/send.h @@ -76,23 +76,9 @@ struct sender { void (*send)(long unsigned current_chunk, long unsigned chunks_sent, const char *buf, size_t len, const char *header_buf, size_t header_len); - /** - * Add file descriptors to fd_sets. - * - * The pre_select function of each supported sender is called just before - * para_server enters its main select loop. Each sender may watch its own - * file descriptors for reading or writing. - * - * \sa select(2). - */ + /** Ask the scheduler to monitor file descriptors. */ void (*pre_select)(struct sched *s); - /** - * Handle the file descriptors which are ready for I/O. - * - * If the pre_select hook asked for one or more file descriptors to be - * watched, this is the hook to check the result and perform I/O on the - * descriptors which are ready for reading/writing. - */ + /** Perform I/O on the file descriptors which are ready. */ void (*post_select)(struct sched *s); /** * Terminate all connected clients. diff --git a/signal.c b/signal.c index 27bda840..e5ef7a41 100644 --- a/signal.c +++ b/signal.c @@ -27,7 +27,7 @@ static int signal_pipe[2]; * signal arrives, the signal handler writes the number of the signal received * to one end of the signal pipe. The application can test for pending signals * by checking if the file descriptor of the other end of the signal pipe is - * ready for reading, see select(2). + * ready for reading. * * \return This function either succeeds or calls exit(3) to terminate the * current process. On success, a signal task structure is returned. diff --git a/signal.h b/signal.h index 35221024..d65d18e3 100644 --- a/signal.h +++ b/signal.h @@ -13,20 +13,19 @@ struct signal_task { }; /** - * A generic pre-select method for signal tasks. + * Monitor the signal fd for reading. * - * \param s Used to watch the signal fd for reading. + * \param s The scheduler instance. * \param context Signal task pointer. * * This convenience helper is called from several programs which need to handle - * signals, including para_server and para_audiod. These programs define a - * signal task structure and set its ->pre_select method to this function which - * adds the file descriptor of the signal task to the set of descriptors to be - * watched in the next select() call. + * signals, including para_server and para_audiod. These programs set up a + * signal pipe and a signal task structure, and use this function to tell the + * scheduler to monitor the read end of the pipe. * * Although the second parameter must be in fact a pointer to a signal_task - * structure, the parameter is specified as void * here to match the - * ->pre_select method of struct task. + * structure, the parameter is specified as void * here to match the signature + * declared in struct \ref task_info. */ _static_inline_ void signal_pre_select(struct sched *s, void *context) { diff --git a/vss.c b/vss.c index fce5281b..49fd7ae2 100644 --- a/vss.c +++ b/vss.c @@ -43,7 +43,7 @@ const struct sender * const senders[] = { enum afs_socket_status { /** Socket is inactive. */ AFS_SOCKET_READY, - /** Socket fd was included in the write fd set for select(). */ + /** Socket fd was monitored for writing. */ AFS_SOCKET_CHECK_FOR_WRITE, /** vss wrote a request to the socket and waits for reply from afs. */ AFS_SOCKET_AFD_PENDING @@ -827,7 +827,7 @@ static void vss_compute_timeout(struct sched *s, struct vss_task *vsst) if (sched_request_barrier(&vsst->data_send_barrier, s) == 1) return; /* - * Compute the select timeout as the minimal time until the next + * Compute the I/O timeout as the minimal time until the next * chunk/slice is due for any client. */ compute_chunk_time(mmd->chunks_sent, &mmd->afd.afhi.chunk_tv, -- 2.39.5