From: Andre Noll Date: Tue, 27 May 2025 22:06:58 +0000 (+0200) Subject: doxygen X-Git-Url: https://git.tuebingen.mpg.de/?a=commitdiff_plain;h=e6f56b7beb277bf25651209488c31f25c297f547;p=paraslash.git doxygen --- diff --git a/play.c b/play.c index a43a1e53..304b1d23 100644 --- a/play.c +++ b/play.c @@ -1,6 +1,17 @@ /* Copyright (C) 2012 Andre Noll , see file COPYING. */ -/** \file play.c Paraslash's standalone player. */ +/** \file play.c Paraslash's standalone player + * + * The para_play(1) is an interactive tool to play audio files in a terminal. + * It employs the buffer tree API to link together the afh receiver, a + * decoder and the default writer (alsa on linux), enabling playback for + * all supported audio formats. + * + * Interactive command line editing is based on the API defined in \ref + * interactive.h. Subcommands of para_play(1) are realized as lopsub + * subcommands. + * + * \cond doxygen_ignore */ #include #include @@ -24,11 +35,9 @@ #include "fd.h" #include "interactive.h" -/** Array of error strings. */ DEFINE_PARA_ERRLIST; static struct lls_parse_result *play_lpr; - #define CMD_PTR (lls_cmd(0, play_suite)) #define OPT_RESULT(_name) \ (lls_opt_result(LSG_PLAY_PARA_PLAY_OPT_ ## _name, play_lpr)) @@ -36,22 +45,22 @@ static struct lls_parse_result *play_lpr; #define OPT_UINT32_VAL(_name) (lls_uint32_val(0, OPT_RESULT(_name))) #define OPT_STRING_VAL(_name) (lls_string_val(0, OPT_RESULT(_name))) -/** +/* * Describes a request to change the state of para_play. * - * There is only one variable of this type: \a rq of the global play task - * structure. Command handlers only set this variable and the post_monitor() - * function of the play task investigates its value during each iteration of - * the scheduler run and performs the actual work. + * There is only one instance of this type in the play task structure, where + * it may be set by command handlers. The post_monitor() function of the + * play task investigates the value during each iteration of the scheduler + * run and performs any actual work to dispatch the change request. */ enum state_change_request_type { - /** Everybody is happy. */ + /* Everybody is happy. */ CRT_NONE, - /** Stream must be repositioned (com_jmp(), com_ff()). */ + /* Stream must be repositioned (com_jmp(), com_ff()). */ CRT_REPOS, - /** New file should be loaded (com_next()). */ + /* New file should be loaded (com_next()). */ CRT_FILE_CHANGE, - /** Someone wants us for dead (com_quit()). */ + /* Someone wants us for dead (com_quit()). */ CRT_TERM_RQ }; @@ -101,7 +110,7 @@ struct play_command_info { static int loglevel = LL_WARNING; -/** The log function which writes log messages to stderr. */ +/* The log function which writes log messages to stderr. */ INIT_STDERR_LOGGING(loglevel); char *stat_item_values[NUM_STAT_ITEMS] = {NULL}; @@ -1173,16 +1182,20 @@ static int play_post_monitor(__a_unused struct sched *s, __a_unused void *contex return 1; } -/** - * The main function of para_play. +/** \endcond doxygen_ignore + * + * The main function of para_play(1). + * + * \param argc Command line options are parsed by the lopsub library. * - * \param argc See man page. - * \param argv See man page. + * \param argv Options are defined in the lopsub suite file of the source + * tree (not part of the doxygen system). The suite file also contains the + * definitions of the various subcommands (stop, pause, etc.). * - * para_play distributes its work by submitting various tasks to the paraslash - * scheduler. The receiver, filter and writer tasks, which are used to play an - * audio file, require one task each to maintain their underlying buffer tree - * node. These tasks only exist when an audio file is playing. + * para_play(1) distributes its work by submitting various tasks to the + * paraslash scheduler. The receiver, filter and writer tasks, which are used + * to play an audio file, require one task each to maintain their underlying + * buffer tree node. These tasks only exist when an audio file is playing. * * The i9 task, which is submitted and maintained by the i9e subsystem, reads * an input line and calls the corresponding command handler such as com_stop() diff --git a/server.c b/server.c index 48ada73c..c551564b 100644 --- a/server.c +++ b/server.c @@ -1,6 +1,13 @@ /* Copyright (C) 1997 Andre Noll , see file COPYING. */ -/** \file server.c Paraslash's main server. */ +/** \file server.c Paraslash's main server. + * + * This file implements the main function of para_server(1) and its core + * functionality, including signal handling and task setup/teardown and TCP + * socket management. + * + * The file also contains a few helpers for other subsystems. + */ #include #include @@ -35,13 +42,18 @@ #include "user_list.h" #include "color.h" -/** Array of error strings. */ +/** \cond doxygen_ignore */ +/* Get a reference to the supercommand of para_server. */ +#define CMD_PTR (lls_cmd(0, server_suite)) + +/* Array of error strings. */ DEFINE_PARA_ERRLIST; __printf_2_3 void (*para_log)(int, const char*, ...) = daemon_log; -/** Shut down non-authorized connections after that many seconds. */ +/* Shut down non-authorized connections after that many seconds. */ #define ALARM_TIMEOUT 10 +/** \endcond doxygen_ignore */ /** * Pointer to shared memory area for communication between para_server @@ -166,9 +178,6 @@ err_out: exit(EXIT_FAILURE); } -/** Get a reference to the supercommand of para_server. */ -#define CMD_PTR (lls_cmd(0, server_suite)) - /** * (Re-)read the server configuration files. * @@ -636,8 +645,19 @@ void free_lpr(void) /** * The main function of para_server. * - * \param argc Usual argument count. - * \param argv Usual argument vector. + * \param argc Command line options are parsed via the lopsub library. + * + * \param argv Options are defined in the lopsub suite file. The various + * subcommands (add, ls, play, etc.) are realized in an independent file. + * + * We fork once at startup to create the afs process. The child calls \ref + * afs_init() of \ref afs.c to initialize the audio file selector. Both + * processes define and register their own set of tasks to the scheduler. + * + * The server processes registers three tasks to handle signals, stream audio, + * or dispatch command requests at the command socket. Incoming requests + * are handled without blocking by forking and having the child call \ref + * handle_connect() of \ref command.c. * * \return EXIT_SUCCESS or EXIT_FAILURE. */