From: sangorrin <sangorrin@35b4ef3e-fd22-0410-ab77-dab3279adceb>
Date: Tue, 20 Mar 2007 10:22:27 +0000 (+0000)
Subject: corrections in network functions
X-Git-Url: https://rtime.felk.cvut.cz/gitweb/frescor/frsh-include.git/commitdiff_plain/62dca3d37b4c223cd8ac904b9b2f3e7097beac99

corrections in network functions

git-svn-id: http://www.frescor.org/private/svn/frescor/frsh/trunk/include@346 35b4ef3e-fd22-0410-ab77-dab3279adceb
---

diff --git a/frsh_distributed.h b/frsh_distributed.h
index 08bc9c4..be1f988 100644
--- a/frsh_distributed.h
+++ b/frsh_distributed.h
@@ -172,19 +172,20 @@
  * split them.
  *
  * Some protocols, like IP, are capable of sending large messages
- * (and use fragmentation internally) but other protocols doesn't
- * provide fragmentation features.
+ * (and use fragmentation internally) but other protocols don't.
  *
  * @param[in] resource_id The network we want the tx time from.
  * @param[in] destination The destination address
  * @param[out] max_size The maximum number of bytes for each message
  *
  * @return
- *   FRSH_NO_ERROR: in this case it also means contract accepted \n
+ *   FRSH_NO_ERROR \n
  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
- *   FRSH_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
- *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ *   a network accessible from the current processing node \n
+ *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
+ *   invalid \n
  *
  **/
 int frsh_network_message_get_max_size
@@ -196,19 +197,21 @@ int frsh_network_message_get_max_size
  * frsh_network_bytes_to_budget()
  *
  * This operation converts a number of bytes into a temporal budget for
- * a specific network. Network overheads are not included here but internally
- * when negotiating a specific contract.
+ * a specific network. Network overheads are not included here but are
+ * considered internally when negotiating a specific contract.
  *
  * @param[in] resource_id The network
  * @param[in] nbytes Number of bytes
  * @param[out] budget The network budget for nbytes
  *
  * @return
- *   FRSH_NO_ERROR: in this case it also means contract accepted \n
+ *   FRSH_NO_ERROR \n
  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
- *   FRSH_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
- *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ *   a network accessible from the current processing node \n
+ *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
+ *   than zero \n
  *
  **/
 int frsh_network_bytes_to_budget
@@ -227,11 +230,13 @@ int frsh_network_bytes_to_budget
  * @param[out] nbytes Number of bytes
  *
  * @return
- *   FRSH_NO_ERROR: in this case it also means contract accepted \n
+ *   FRSH_NO_ERROR \n
  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
- *   FRSH_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
- *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ *   a network accessible from the current processing node \n
+ *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
+ *   an invalid time value \n
  *
  **/
 int frsh_network_budget_to_bytes
@@ -244,25 +249,26 @@ int frsh_network_budget_to_bytes
  *
  * This operation gets the minimum effective budget for a network. Each message
  * consumes a contracted budget in "chunks" (i.e: packets) that we call
- * effective budget.
+ * minimum effective budget.
  *
  * A negotiated contract, for N bytes in a period T, means that there is a
  * virtual resource that reserves for the user:
  *
- *         (N bytes)/budget_to_bytes(min_effective_budget) "CHUNKS"
+ *   Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
  *
  * Note that if the user decides not to send these N bytes at once but, say,
- * one byte at a time, it will consume more "CHUNKS" and the reserved budget
- * will become exhausted before sending all the bytes.
+ * one byte at a time, it will consume one "CHUNK" at a time and the reserved
+ * budget will become exhausted before sending all the bytes.
  *
  * @param[in] resource_id The network
  * @param[out] budget The network budget
  *
  * @return
- *   FRSH_NO_ERROR: in this case it also means contract accepted \n
+ *   FRSH_NO_ERROR \n
  *   FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
  *   FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
- *   FRSH_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ *   FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ *   a network accessible from the current processing node \n
  *   FRSH_ERR_BAD_ARGUMENT: if pointers are NULL \n
  *
  **/