From: Andre Noll Date: Sun, 22 May 2011 13:22:42 +0000 (+0200) Subject: Merge branch 't/decl_after_statement' X-Git-Tag: v0.4.7~4 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=d91b2b2a70c85562b5d30cc5fda46468532e314a;hp=5c78b78108bca6fc0ff883eb178fa5c15d226039 Merge branch 't/decl_after_statement' --- diff --git a/Doxyfile b/Doxyfile index fcfe4043..81e414d5 100644 --- a/Doxyfile +++ b/Doxyfile @@ -622,7 +622,8 @@ EXCLUDE_PATTERNS = *.cmdline.* \ gui* \ gcc-compat.h \ fade.c \ - config.h + config.h \ + *_command_list.[ch] # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN index 15c38794..32802232 100755 --- a/GIT-VERSION-GEN +++ b/GIT-VERSION-GEN @@ -31,8 +31,10 @@ echo "$VN" [[ -z "$GVF" ]] && exit 0 if [[ -r "$GVF" ]]; then - VC=$(sed -e 's/^#define GIT_VERSION "//; s/"$//' < "$GVF") + pattern='^#define GIT_VERSION "' + VC=$(grep "$pattern" < "$GVF" | sed -e "s/$pattern//; s/\"$//") [[ "$VN" == "$VC" ]] && exit 0 fi echo >&2 "new git version: $VN" -echo "#define GIT_VERSION \"$VN\"" >$GVF +echo "/** \\file ${GVF##*/} Auto-generated version file. Do not edit. */" >$GVF +echo "#define GIT_VERSION \"$VN\"" >> $GVF diff --git a/NEWS b/NEWS index bf6f2bab..c56fc719 100644 --- a/NEWS +++ b/NEWS @@ -2,6 +2,9 @@ 0.4.7 (to be announced) "infinite rollback" ------------------------------------------- +The new ao writer, support for ssh RSA keys and a couple of other +enhancements. + - Support for ESD, Pulseaudio, AIX, Solaris, IRIX and other platforms through the libao audio library. - Support for RSA keys generated with ssh-keygen. @@ -10,6 +13,7 @@ - The autogen script detects the number of processors and runs a parallel make if possible. - Major cleanup of the crypto API. + - Documentation updates. ------------------------------------------ 0.4.6 (2011-03-31) "deterministic entropy" diff --git a/aac_common.c b/aac_common.c index 14662fdd..9e46a77c 100644 --- a/aac_common.c +++ b/aac_common.c @@ -15,8 +15,9 @@ #include "error.h" /** - * get a new libfaad decoder handle + * Get a new libfaad decoder handle. * + * \return The handle returned by NeAACDecOpen(). */ NeAACDecHandle aac_open(void) { diff --git a/buffer_tree.c b/buffer_tree.c index 0e460dd3..88fb8362 100644 --- a/buffer_tree.c +++ b/buffer_tree.c @@ -257,6 +257,8 @@ static void btr_pool_deallocate(struct btr_pool *btrp, size_t size) * * \param bnd Specifies how to create the new node. * + * \return A pointer to the newly allocated node. + * * This function always succeeds (or calls exit()). The returned pointer must * be freed using btr_free_node() after the node has been removed from the * buffer tree via btr_remove_node(). @@ -660,6 +662,11 @@ void btr_consume(struct btr_node *btrn, size_t numbytes) return btr_consume(btrn, sz); } +/** + * Clear the input queue of a buffer tree node. + * + * \param btrn The node whose input queue should be cleared. + */ void btr_drain(struct btr_node *btrn) { struct btr_buffer_reference *br, *tmp; @@ -771,8 +778,8 @@ void btr_splice_out_node(struct btr_node *btrn) * * \param btrn The node whose output queue size should be computed. * - * This function iterates over all children of the given node and returns the - * size of the largest input queue. + * \return This function iterates over all children of the given node and + * returns the size of the largest input queue. */ size_t btr_get_output_queue_size(struct btr_node *btrn) { @@ -827,8 +834,9 @@ int btr_exec_up(struct btr_node *btrn, const char *command, char **value_result) /** * Obtain the context of a buffer node tree. * - * The returned pointer equals the context pointer used at creation time of the - * node. + * \param btrn The node whose output queue size should be computed. + * + * \return A pointer to the \a context address specified at node creation time. * * \sa btr_new_node(), struct \ref btr_node_description. */ diff --git a/filter.h b/filter.h index 0808059d..94657a73 100644 --- a/filter.h +++ b/filter.h @@ -24,8 +24,11 @@ struct filter_node { struct list_head callbacks; /** A pointer to the configuration of this instance. */ void *conf; + /** The buffer tree node. */ struct btr_node *btrn; + /** The task corresponding to this filter node. */ struct task task; + /** The minimal input queue size, see \ref btr_node_status(). */ size_t min_iqs; }; @@ -136,6 +139,7 @@ static inline void write_int16_host_endian(char *buf, int val) DECLARE_FILTER_INITS +/** Iterate over the array of supported filters. */ #define FOR_EACH_SUPPORTED_FILTER(j) for (j = 0; j < NUM_SUPPORTED_FILTERS; j++) /** The filter array, one structure for each supported filter. */ diff --git a/filter_common.c b/filter_common.c index 566d97ed..4b1a45de 100644 --- a/filter_common.c +++ b/filter_common.c @@ -108,6 +108,11 @@ int check_filter_arg(char *fa, void **conf) return -E_UNSUPPORTED_FILTER; } +/** + * Print help text of each filter to stdout. + * + * \param detailed If non-zero, print detailed help. + */ void print_filter_helps(int detailed) { int i; @@ -127,6 +132,17 @@ void print_filter_helps(int detailed) } } +/** + * Set select timeout of the the scheduler. + * + * \param s The scheduler. + * \param t The task struct of this filter. + * + * This looks at the status of the btr node of the filter. If data is available + * in the input queue of the filter, or if an error occured, a minimal timeout + * for the next select call is requested from the scheduler. Otherwise the + * scheduler timeout is left unchanged. + */ void generic_filter_pre_select(struct sched *s, struct task *t) { struct filter_node *fn = container_of(t, struct filter_node, task); diff --git a/para.h b/para.h index 7217486d..5dc39124 100644 --- a/para.h +++ b/para.h @@ -176,7 +176,7 @@ _static_inline_ long int para_random(unsigned max) */ #define EXPR_BUILD_ASSERT(cond) (sizeof(char [1 - 2 * !(cond)]) - 1) -/* &a[0] degrades to a pointer: a different type from an array */ +/** &a[0] degrades to a pointer: a different type from an array */ #define _array_size_chk(arr) EXPR_BUILD_ASSERT(\ !__builtin_types_compatible_p(typeof(arr), typeof(&(arr)[0]))) /** Get the size of an array */ @@ -200,6 +200,7 @@ _static_inline_ long int para_random(unsigned max) /** Data that indicates an eof-condition for a fec-encoded stream. */ #define FEC_EOF_PACKET "\xec\x0d\xcc\xfe\0\0\0\0" \ "\0\0\0\0\0\0\0\0" "\0\0\0\0\0\0\0\0" "\0\0\0\0\0\0\0\0" +/** The number of bytes of the \a FEC_EOF_PACKET. */ #define FEC_EOF_PACKET_LEN 32 /** Used to avoid a shortcoming in vim's syntax highlighting. */ @@ -228,10 +229,12 @@ _static_inline_ long int para_random(unsigned max) SAMPLE_FORMAT(SF_U16_LE, "16 bit unsigned, little endian"), \ SAMPLE_FORMAT(SF_U16_BE, "16 bit unsigned, big endian"), \ +/** \cond */ #define SAMPLE_FORMAT(a, b) a enum sample_format {SAMPLE_FORMATS}; #undef SAMPLE_FORMAT #define SAMPLE_FORMAT(a, b) b +/** \endcond */ /** Debug loglevel, gets really noisy. */ #define LL_DEBUG 0 diff --git a/recv.h b/recv.h index 05c5ed76..ee8138f9 100644 --- a/recv.h +++ b/recv.h @@ -50,6 +50,12 @@ struct receiver { * \a argc and \a argv. */ void *(*parse_config)(int argc, char **argv); + /** + * Deallocate the configuration structure of a receiver node. + * + * This calls the receiver-specific cleanup function generated by + * gengetopt. + */ void (*free_config)(void *conf); /** * Open one instance of the receiver. diff --git a/recv_common.c b/recv_common.c index 3fe2a139..f38184b4 100644 --- a/recv_common.c +++ b/recv_common.c @@ -123,6 +123,18 @@ void print_receiver_helps(int detailed) } } +/** + * Simple pre-select hook, used by all receivers. + * + * \param s Scheduler info. + * \param t Determines the receiver node. + * + * This requests a minimal delay from the scheduler if the status of the buffer + * tree node indicates an error/eof condition. No file descriptors are added to + * the fd sets of \a s. + * + * \return Standard. + */ int generic_recv_pre_select(struct sched *s, struct task *t) { struct receiver_node *rn = container_of(t, struct receiver_node, task); diff --git a/ringbuffer.c b/ringbuffer.c index bf990b06..15d767e6 100644 --- a/ringbuffer.c +++ b/ringbuffer.c @@ -96,7 +96,7 @@ void *ringbuffer_get(struct ringbuffer *rb, int num) * * \param rb The ringbuffer identifier * - * This function always succeeds and never returns a number greater than the + * \return This function always succeeds. It returns a number less than the * size of the ring buffer. */ unsigned ringbuffer_filled(struct ringbuffer *rb) diff --git a/version.h b/version.h index 3b839669..a9547797 100644 --- a/version.h +++ b/version.h @@ -1,11 +1,13 @@ +/** \file version.h Macros for printing the version string. */ + #include "git-version.h" -/** Version text used by various commands if -V switch was given. */ + +/** Version text printed by all executables if -V was given. */ #define VERSION_TEXT(prefix) "para_" prefix " " PACKAGE_VERSION \ " (" GIT_VERSION ": " CODENAME ")" "\n" \ "Copyright (C) 2011 Andre Noll\n" \ "This is free software with ABSOLUTELY NO WARRANTY." \ " See COPYING for details.\n" \ - "Written by Andre Noll.\n" \ "Report bugs to .\n" /** Print out \p VERSION_TEXT and exit if version flag was given. */ diff --git a/write.h b/write.h index 0044ae4f..8a60294d 100644 --- a/write.h +++ b/write.h @@ -19,8 +19,11 @@ struct writer_node { void *private_data; /** The writer-specific configuration of this node. */ void *conf; + /** The buffer tree node associated with this writer node. */ struct btr_node *btrn; + /** The task of this writer node. */ struct task task; + /** The minimal input queue size (size of one audio sample). */ size_t min_iqs; }; @@ -70,12 +73,19 @@ struct writer { */ void (*close)(struct writer_node *); /** - * Shutdown the writer + * Shutdown the writer. * * This is a optional function pointer used for cleaning up. */ void (*shutdown)(struct writer_node *); + /** The short and the log help text of this writer. */ struct ggo_help help; + /** + * The callback handler. + * + * Each writer may provide an ->execute callback which can be used for + * inter-node communication. + */ btr_command_handler execute; }; diff --git a/write_common.c b/write_common.c index 5988faf7..faf20749 100644 --- a/write_common.c +++ b/write_common.c @@ -35,10 +35,10 @@ void writer_init(void) writers[i].init(&writers[i]); } /** - * check if given string is a valid command line for any writer + * Check if given string is a valid command line for any writer. * - * \param \wa string of the form writer_name:options - * \param writer_num contains the number of the writer upon success + * \param \wa String of the form writer_name:options. + * \param writer_num Contains the number of the writer upon success. * * This function checks whether \a wa starts with the name of a supported * paraslash writer, optionally followed by a colon and any options for that @@ -98,20 +98,24 @@ void register_writer_node(struct writer_node *wn, struct btr_node *parent) } /** - * Setup a writer node with the default writer. + * Parse config and register a task for a writer node. * - * If arg is \p NULL, the OS-dependent default writer is used with an empty - * configuration string. It defaults to alsa for Linux, osx for OS X, oss for - * *BSD and the file writer if neither of these is supported. + * \param arg Command line arguments. + * \param parent The new node will be a child of \a parent. + * \param wn The writer node. * - * Once the writer configuration has been retrieved, a writer node is created, - * its buffer tree node is added to the buffer tree as a child of the given - * parent. + * If arg is \p NULL, the OS-dependent default writer is used with no + * arguments. The default writers are alsa for Linux, osx for OS X, oss for + * *BSD, and the file writer if the default writer is not supported. * - * Finally, the new writer node's taks structure is initialized and registered + * Once the writer configuration has been retrieved from the ->parse_config + * callback a writer node is created, its buffer tree node is added to the + * buffer tree as a child of the given parent. + * + * Finally, the new writer node's task structure is initialized and registered * to the paraslash scheduler. * - * \return A pointer to the allocated writer node group. + * \return Standard. */ int setup_writer_node(const char *arg, struct btr_node *parent, struct writer_node *wn)