X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=src%2Fsn_network.h;h=f56e3ca288b0f0034b7e33f8c32be4b15f8825fc;hb=2b64b183834075911f9e53a6f0132d116bf45a76;hp=a734cadb30e8d29d5bd65600d3023d705ad95417;hpb=f3635d61e91198d4a40126bab3e4a3c1b1e49724;p=sort-networks.git

diff --git a/src/sn_network.h b/src/sn_network.h
index a734cad..f56e3ca 100644
--- a/src/sn_network.h
+++ b/src/sn_network.h
@@ -51,10 +51,11 @@ typedef struct sn_network_s sn_network_t;
 #define SN_NETWORK_INPUT_NUM(n) (n)->inputs_num
 
 /**
- * Creates an empty comparator network and returns a pointer to it.
+ * Creates an empty comparator network and returns a pointer to it. The
+ * comparator network must be freed using sn_network_destroy().
  *
  * \param inputs_num Number of inputs the comparator network has.
- * \return Pointer to the comparator network or NULL on error.
+ * \return Pointer to the comparator network or \c NULL on error.
  */
 sn_network_t *sn_network_create (int inputs_num);
 
@@ -62,16 +63,17 @@ sn_network_t *sn_network_create (int inputs_num);
  * Clones an existing comparator network.
  *
  * \param n Comparator network to clone.
- * \return Copied sort network or NULL on error. The returned network must be
- *   freed using sn_network_destroy().
+ * \return Copied sort network or \c NULL on error. The returned network must
+ *   be freed using sn_network_destroy().
  */
 sn_network_t *sn_network_clone (const sn_network_t *n);
 
 /**
  * Destroys a comparator network allocated with sn_network_create() or one of
- * the other methods returning a sn_network_t. This frees all allocated space.
+ * the other methods returning a \c sn_network_t. This frees all allocated
+ * space.
  *
- * \param n The comparator network to destroy. May be NULL.
+ * \param n The comparator network to destroy. May be \c NULL.
  */
 void sn_network_destroy (sn_network_t *n);
 
@@ -79,12 +81,21 @@ void sn_network_destroy (sn_network_t *n);
  * Creates a new sort network using Batcher's Odd-Even-Mergesort algorithm.
  *
  * \param inputs_num Number of inputs / outputs of the sorting network.
- * \return A pointer to the newly allocated sorting network or NULL if an
+ * \return A pointer to the newly allocated sorting network or \c NULL if an
  *   invalid number of inputs was given or allocation failed.
  */
 sn_network_t *sn_network_create_odd_even_mergesort (int inputs_num);
 
 /**
+ * Creates a new sorting network using the Pairwise sorting algorithm published
+ * by Ian Parberry.
+ * \param inputs_num Number of inputs / outputs of the sorting network.
+ * \return A pointer to the newly allocated sorting network or \c NULL if an
+ *   invalid number of inputs was given or allocation failed.
+ */
+sn_network_t *sn_network_create_pairwise (int inputs_num);
+
+/**
  * Append a new stage to a comparator network.
  *
  * \param n The comparator network to which to add the stage.
@@ -125,7 +136,7 @@ int sn_network_comparator_add (sn_network_t *n, const sn_comparator_t *c);
  *
  * \param n Comparator network to work with.
  * \return The number of comparators contained in the network or less than zero
- *  on error (n is NULL).
+ *  on error (\c n is \c NULL).
  */
 int sn_network_get_comparator_num (const sn_network_t *n);
 
@@ -139,6 +150,7 @@ int sn_network_get_comparator_num (const sn_network_t *n);
  *   comparator network. Otherwise, segmentation faults or memory corruption
  *   will occur.
  * \return Zero on success, non-zero on failure.
+ * \see sn_stage_sort
  */
 int sn_network_sort (sn_network_t *n, int *values);
 
@@ -153,6 +165,13 @@ int sn_network_sort (sn_network_t *n, int *values);
  */
 int sn_network_brute_force_check (sn_network_t *n);
 
+/**
+ * Prints the comparator network to \c STDOUT using a human readable
+ * representation.
+ *
+ * \param n The comparator network to display.
+ * \return Zero on success, non-zero on failure.
+ */
 int sn_network_show (sn_network_t *n);
 
 /**
@@ -218,8 +237,8 @@ sn_network_t *sn_network_combine (sn_network_t *n0, sn_network_t *n1);
  *
  * \param n0 First network.
  * \param n1 Second network.
- * \return Newly allocated network with twice the number of inputs or NULL on
- *   error.
+ * \return Newly allocated network with twice the number of inputs or \c NULL
+ *   on error.
  */
 sn_network_t *sn_network_combine_bitonic_merge (sn_network_t *n0, sn_network_t *n1);
 
@@ -228,17 +247,75 @@ sn_network_t *sn_network_combine_bitonic_merge (sn_network_t *n0, sn_network_t *
  *
  * \param n0 First network.
  * \param n1 Second network.
- * \return Newly allocated network or NULL on error.
+ * \return Newly allocated network or \c NULL on error.
  */
 sn_network_t *sn_network_combine_odd_even_merge (sn_network_t *n0, sn_network_t *n1);
 
+/**
+ * Reads a comparator network from a open file handle.
+ *
+ * \param fh The FILE pointer to read from.
+ * \return A newly allocated comparator network or \c NULL on error.
+ * \see sn_network_read_file
+ */
 sn_network_t *sn_network_read (FILE *fh);
+
+/**
+ * Reads a comparator network from a file.
+ *
+ * \param file File name to read the network from.
+ * \return A newly allocated comparator network or \c NULL on error.
+ * \see sn_network_read
+ */
 sn_network_t *sn_network_read_file (const char *file);
+
+/**
+ * Writes a comparator network to a file handle.
+ *
+ * \param n The comparator network to write.
+ * \param fh The file handle to write to. Must be opened in write mode.
+ * \return Zero on success, non-zero on failure.
+ * \see sn_network_write_file
+ */
 int sn_network_write (sn_network_t *n, FILE *fh);
+
+/**
+ * Writes a comparator network to a file.
+ *
+ * \param n The comparator network to write.
+ * \param fh The file name to write the network to.
+ * \return Zero on success, non-zero on failure.
+ * \see sn_network_write
+ */
 int sn_network_write_file (sn_network_t *n, const char *file);
 
+/**
+ * Creates a serialized form of the given comparator network. The serialized
+ * form is byte-order independent and can easily be sent over a computer
+ * network.
+ *
+ * \param n The comparator network to serialize.
+ * \param[out] ret_buffer Pointer to a pointer into which the location of the
+ *   allocated memory will be written. It is the caller's responsibility to
+ *   free this memory.
+ * \param[out] ret_buffer_size Pointer to a size_t into which the size of the
+ *   allocated memory will be written.
+ * \return Zero on success, non-zero on failure.
+ * \see sn_network_unserialize
+ */
 int sn_network_serialize (sn_network_t *n, char **ret_buffer,
     size_t *ret_buffer_size);
+
+/**
+ * Creates a comparator network from its serialized form.
+ *
+ * \param buffer Pointer to a buffer containing the comparator network in
+ *   serialized form.
+ * \param buffer_size Size of the buffer (in bytes).
+ * \return Pointer to the newly allocated comparator network or \c NULL on
+ *   error.
+ * \see sn_network_serialize
+ */
 sn_network_t *sn_network_unserialize (char *buffer, size_t buffer_size);
 #endif /* SN_NETWORK_H */