/* Copyright (C) 2012 Andre Noll <maan@tuebingen.mpg.de>, 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 <signal.h>
#include <lopsub.h>
#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))
#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
};
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};
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()
/* Copyright (C) 1997 Andre Noll <maan@tuebingen.mpg.de>, 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 <netinet/in.h>
#include <sys/socket.h>
#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
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.
*
/**
* 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.
*/
projects / paraslash.git / commitdiff