#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)
{
*
* \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().
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;
*
* \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)
{
/**
* 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.
*/
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;
};
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. */
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;
}
}
+/**
+ * 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);
*/
#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 */
/** 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. */
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
* \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.
}
}
+/**
+ * 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);
*
* \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)
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;
};
*/
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;
};
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
}
/**
- * 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)
projects / paraslash.git / commitdiff