From aedb88c4afbb1af275eb8b5a04ade11528062b28 Mon Sep 17 00:00:00 2001 From: Florian Forster Date: Mon, 17 May 2010 10:49:12 +0200 Subject: [PATCH] src/sn_stage.h: Begin adding Doxygen documentation. --- src/sn_stage.h | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 88 insertions(+), 7 deletions(-) diff --git a/src/sn_stage.h b/src/sn_stage.h index 192887a..e2b57a6 100644 --- a/src/sn_stage.h +++ b/src/sn_stage.h @@ -31,47 +31,128 @@ #include "sn_comparator.h" +/** + * Struct representing a stage of the comparator network. Don't modify this + * struct yourself, use the sn_stage_* methods instead. + */ struct sn_stage_s { - int depth; - sn_comparator_t *comparators; - int comparators_num; + int depth; /**< Depth of this stage, where zero means closest to the input. */ + sn_comparator_t *comparators; /**< Pointer to a list of comparators contained in this stage. */ + int comparators_num; /**< Number of comparators in this stage. */ }; typedef struct sn_stage_s sn_stage_t; +/** + * Direction into which to cut. + * + * \see sn_network_cut_at, sn_stage_cut_at + */ enum sn_network_cut_dir_e { - DIR_MIN, - DIR_MAX + DIR_MIN, /**< Assume negative infinity. */ + DIR_MAX /**< Assume positive infinity. */ }; #define SN_STAGE_DEPTH(s) (s)->depth #define SN_STAGE_COMP_NUM(s) (s)->comparators_num #define SN_STAGE_COMP_GET(s,n) ((s)->comparators + (n)) +/** + * Creates an empty stage and returns a pointer to it. The stage must be freed + * using sn_stage_destroy(). + * + * \param depth Depth of the stage within the comparator network. This will be + * re-set by sn_network_stage_add(). + * \return Pointer to the comparator network or \c NULL on error. + */ sn_stage_t *sn_stage_create (int depth); /** * Clones an existing stage. * * \param s Stage to clone. - * \return Copied stage or NULL on error. The returned stage must be freed + * \return Copied stage or \c NULL on error. The returned stage must be freed * using sn_stage_destroy(). */ sn_stage_t *sn_stage_clone (const sn_stage_t *s); + +/** + * Destroys a stage allocated with sn_stage_create() or one of the other + * methods returning a \c sn_stage_t. This frees all allocated space. + * + * \param s The stage to destroy. May be \c NULL. + */ void sn_stage_destroy (sn_stage_t *s); +/** + * Applies a stage to an array of integers. + * + * \param s Pointer to the stage. + * \param[in,out] values Pointer to integer values to sort. The number of + * integer values pointed to must be at least the number of inputs of the + * comparator network. Otherwise, segmentation faults or memory corruption + * will occur. + * \return Zero on success, non-zero on failure. + * \see sn_network_sort + */ int sn_stage_sort (sn_stage_t *s, int *values); +/** + * Adds a comparator to a stage. If this would return in a conflict (a + * comparator using on of the line already exists in this stage) an error is + * returned. + * + * \param s Pointer to the stage. + * \param c Pointer to a comparator to add. The given comparator is copied. It + * is the caller's responsibility to free c. + * \return Zero on success, non-zero on failure. + * \see sn_stage_comparator_remove + */ int sn_stage_comparator_add (sn_stage_t *s, const sn_comparator_t *c); -int sn_stage_comparator_remove (sn_stage_t *s, int c_num); + + +/** + * Removed a comparator from a stage. + * + * \param s The stage from which to remove the comparator. + * \param index The index of the comparator to remove. + * \return Zero on success, non-zero on failure. + * \see sn_stage_comparator_add + */ +int sn_stage_comparator_remove (sn_stage_t *s, int index); + +/** + * Checks whether the given comparator can be added to a stage, i.e. if neither + * line if used by another comparator. + * + * \param s Pointer to the stage. + * \param c Pointer to the comparator. + * \return Zero if there is no conflict, one if there is a conflict and two if + * the comparator is already present in the stage. + */ int sn_stage_comparator_check_conflict (sn_stage_t *s, const sn_comparator_t *c); int sn_stage_show (sn_stage_t *s); int sn_stage_invert (sn_stage_t *s); int sn_stage_shift (sn_stage_t *s, int sw, int inputs_num); int sn_stage_swap (sn_stage_t *s, int con0, int con1); + +/** + * Removes an input / line by assuming positive or negative infinity is applied + * to one line. + * + * \param s The stage to work with. + * \param input The input / line on which is assumed to be positive or negative + * infinity. + * \param dir Direction in which to cut; whether positive or negative infinity + * is assumed. + * \return The new position of the infinite value on success or less than zero + * on failure. + * \see sn_network_cut_at + */ int sn_stage_cut_at (sn_stage_t *s, int input, enum sn_network_cut_dir_e dir); + int sn_stage_remove_input (sn_stage_t *s, int input); sn_stage_t *sn_stage_read (FILE *fh); -- 2.11.0