[GNUnet-SVN] r26720 - gnunet/src/ats

[gnunet]

Author: wachs
Date: 2013-04-02 16:25:30 +0200 (Tue, 02 Apr 2013)
New Revision: 26720

Modified:
   gnunet/src/ats/gnunet-service-ats_addresses.c
   gnunet/src/ats/gnunet-service-ats_addresses.h
Log:
documentation


Modified: gnunet/src/ats/gnunet-service-ats_addresses.c
===================================================================
--- gnunet/src/ats/gnunet-service-ats_addresses.c       2013-04-02 13:31:20 UTC 
(rev 26719)
+++ gnunet/src/ats/gnunet-service-ats_addresses.c       2013-04-02 14:25:30 UTC 
(rev 26720)
@@ -688,6 +688,19 @@
 }
 
 
+
+/**
+ * Add a new address for a peer.
+ *
+ * @param handle the address handle to use
+ * @param peer peer
+ * @param plugin_name transport plugin name
+ * @param plugin_addr plugin address
+ * @param plugin_addr_len length of the plugin address
+ * @param session_id session id, can be 0
+ * @param atsi performance information for this address
+ * @param atsi_count number of performance information contained
+ */
 void
 GAS_addresses_add (struct GAS_Addresses_Handle *handle,
                    const struct GNUNET_PeerIdentity *peer,
@@ -786,6 +799,21 @@
 }
 
 
+/**
+ * Update an address with a session or performance information for a peer.
+ *
+ * If an address was added without a session it will be updated with the
+ * session
+ *
+ * @param handle the address handle to use
+ * @param peer peer
+ * @param plugin_name transport plugin name
+ * @param plugin_addr plugin address
+ * @param plugin_addr_len length of the plugin address
+ * @param session_id session id, can be 0
+ * @param atsi performance information for this address
+ * @param atsi_count number of performance information contained
+ */
 void
 GAS_addresses_update (struct GAS_Addresses_Handle *handle,
                       const struct GNUNET_PeerIdentity *peer,
@@ -940,11 +968,24 @@
   return GNUNET_OK;
 }
 
+
+/**
+ * Remove an address or just a session for a peer.
+ *
+ * @param handle the address handle to use
+ * @param peer peer
+ * @param plugin_name transport plugin name
+ * @param plugin_addr plugin address
+ * @param plugin_addr_len length of the plugin address
+ * @param session_id session id, can be 0
+ */
 void
 GAS_addresses_destroy (struct GAS_Addresses_Handle *handle,
                        const struct GNUNET_PeerIdentity *peer,
-                       const char *plugin_name, const void *plugin_addr,
-                       size_t plugin_addr_len, uint32_t session_id)
+                       const char *plugin_name,
+                       const void *plugin_addr,
+                       size_t plugin_addr_len,
+                       uint32_t session_id)
 {
   struct ATS_Address *ea;
   struct DestroyContext dc;
@@ -978,11 +1019,33 @@
 }
 
 
+/**
+ * Notification about active use of an address.
+ * in_use == GNUNET_YES:
+ *     This address is used to maintain an active connection with a peer.
+ * in_use == GNUNET_NO:
+ *     This address is no longer used to maintain an active connection with a 
peer.
+ *
+ * Note: can only be called with in_use == GNUNET_NO if called with GNUNET_YES
+ * before
+ *
+ * @param handle the address handle to use
+ * @param peer peer
+ * @param plugin_name transport plugin name
+ * @param plugin_addr plugin address
+ * @param plugin_addr_len length of the plugin address
+ * @param session_id session id, can be 0
+ * @param in_use GNUNET_YES if GNUNET_NO
+ * @return GNUNET_SYSERR on failure (address unknown ...)
+ */
 int
 GAS_addresses_in_use (struct GAS_Addresses_Handle *handle,
                       const struct GNUNET_PeerIdentity *peer,
-                      const char *plugin_name, const void *plugin_addr,
-                      size_t plugin_addr_len, uint32_t session_id, int in_use)
+                      const char *plugin_name,
+                      const void *plugin_addr,
+                      size_t plugin_addr_len,
+                      uint32_t session_id,
+                      int in_use)
 {
   struct ATS_Address *ea;
 
@@ -1030,7 +1093,7 @@
  * Cancel address suggestions for a peer
  *
  * @param handle the address handle
- * @param peer the respective peer
+ * @param peer the peer id
  */
 void
 GAS_addresses_request_address_cancel (struct GAS_Addresses_Handle *handle,
@@ -1064,10 +1127,10 @@
 
 
 /**
- * Add an address suggestions for a peer
+ * Request address suggestions for a peer
  *
  * @param handle the address handle
- * @param peer the respective peer
+ * @param peer the peer id
  */
 void
 GAS_addresses_request_address (struct GAS_Addresses_Handle *handle,
@@ -1145,6 +1208,15 @@
 }
 
 
+/**
+ * Reset suggestion backoff for a peer
+ *
+ * Suggesting addresses is blocked for ATS_BLOCKING_DELTA. Blocking can be
+ * reset using this function
+ *
+ * @param handle the address handle
+ * @param peer the peer id
+ */
 void
 GAS_addresses_handle_backoff_reset (struct GAS_Addresses_Handle *handle,
                                     const struct GNUNET_PeerIdentity *peer)
@@ -1161,6 +1233,15 @@
 }
 
 
+/**
+ * Change the preference for a peer
+ *
+ * @param handle the address handle
+ * @param client the client sending this request
+ * @param peer the peer id
+ * @param kind the preference kind to change
+ * @param score the new preference score
+ */
 void
 GAS_addresses_change_preference (struct GAS_Addresses_Handle *handle,
                                  void *client,
@@ -1348,10 +1429,14 @@
 
 
 /**
- * Initialize address subsystem.
+ * Initialize address subsystem. The addresses subsystem manages the addresses
+ * known and current performance information. It has a solver component
+ * responsible for the resource allocation. It tells the solver about changes
+ * and receives updates when the solver changes the ressource allocation.
  *
  * @param cfg configuration to use
  * @param stats the statistics handle to use
+ * @return an address handle
  */
 struct GAS_Addresses_Handle *
 GAS_addresses_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
@@ -1484,6 +1569,11 @@
 }
 
 
+/**
+ * Remove all addresses
+ *
+ * @param handle the address handle to use
+ */
 void
 GAS_addresses_destroy_all (struct GAS_Addresses_Handle *handle)
 {
@@ -1501,6 +1591,8 @@
 
 /**
  * Shutdown address subsystem.
+ *
+ * @param handle the address handle to shutdown
  */
 void
 GAS_addresses_done (struct GAS_Addresses_Handle *handle)
@@ -1550,16 +1642,18 @@
   return GNUNET_OK;
 }
 
+
 /**
- * Return all peers currently known to ATS
+ * Return information all peers currently known to ATS
  *
- * @param handle the address handle
- * @param p_it the iterator to call for every peer, callbach with id == NULL
- *        when done
+ * @param handle the address handle to use
+ * @param p_it the iterator to call for every peer
  * @param p_it_cls the closure for the iterator
  */
 void
-GAS_addresses_iterate_peers (struct GAS_Addresses_Handle *handle, 
GNUNET_ATS_Peer_Iterator p_it, void *p_it_cls)
+GAS_addresses_iterate_peers (struct GAS_Addresses_Handle *handle,
+                                                                               
                                 GNUNET_ATS_Peer_Iterator p_it,
+                                                                               
                                 void *p_it_cls)
 {
   struct PeerIteratorContext ip_ctx;
   unsigned int size;
@@ -1580,6 +1674,7 @@
   p_it (p_it_cls, NULL);
 }
 
+
 struct PeerInfoIteratorContext
 {
   GNUNET_ATS_PeerInfo_Iterator it;
@@ -1616,9 +1711,9 @@
 
 
 /**
- * Return all peers currently known to ATS
+ * Return information all peers currently known to ATS
  *
- * @param handle the address handle
+ * @param handle the address handle to use
  * @param peer the respective peer
  * @param pi_it the iterator to call for every peer
  * @param pi_it_cls the closure for the iterator

Modified: gnunet/src/ats/gnunet-service-ats_addresses.h
===================================================================
--- gnunet/src/ats/gnunet-service-ats_addresses.h       2013-04-02 13:31:20 UTC 
(rev 26719)
+++ gnunet/src/ats/gnunet-service-ats_addresses.h       2013-04-02 14:25:30 UTC 
(rev 26720)
@@ -438,10 +438,11 @@
 GAS_addresses_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
                     const struct GNUNET_STATISTICS_Handle *stats);
 
+
 /**
  * Shutdown address subsystem.
  *
- * @param the address handle to shutdown
+ * @param handle the address handle to shutdown
  */
 void
 GAS_addresses_done (struct GAS_Addresses_Handle *handle);
@@ -498,26 +499,67 @@
                       uint32_t session_id,
                       int in_use);
 
+
+/**
+ * Update an address with a session or performance information for a peer.
+ *
+ * If an address was added without a session it will be updated with the
+ * session
+ *
+ * @param handle the address handle to use
+ * @param peer peer
+ * @param plugin_name transport plugin name
+ * @param plugin_addr plugin address
+ * @param plugin_addr_len length of the plugin address
+ * @param session_id session id, can be 0
+ * @param atsi performance information for this address
+ * @param atsi_count number of performance information contained
+ */
 void
 GAS_addresses_update (struct GAS_Addresses_Handle *handle,
                       const struct GNUNET_PeerIdentity *peer,
-                      const char *plugin_name, const void *plugin_addr,
-                      size_t plugin_addr_len, uint32_t session_id,
+                      const char *plugin_name,
+                      const void *plugin_addr,
+                      size_t plugin_addr_len,
+                      uint32_t session_id,
                       const struct GNUNET_ATS_Information *atsi,
                       uint32_t atsi_count);
 
 
+/**
+ * Remove an address or just a session for a peer.
+ *
+ * @param handle the address handle to use
+ * @param peer peer
+ * @param plugin_name transport plugin name
+ * @param plugin_addr plugin address
+ * @param plugin_addr_len length of the plugin address
+ * @param session_id session id, can be 0
+ */
 void
 GAS_addresses_destroy (struct GAS_Addresses_Handle *handle,
                        const struct GNUNET_PeerIdentity *peer,
-                       const char *plugin_name, const void *plugin_addr,
-                       size_t plugin_addr_len, uint32_t session_id);
+                       const char *plugin_name,
+                       const void *plugin_addr,
+                       size_t plugin_addr_len,
+                       uint32_t session_id);
 
 
+/**
+ * Remove all addresses
+ *
+ * @param handle the address handle to use
+ */
 void
 GAS_addresses_destroy_all (struct GAS_Addresses_Handle *handle);
 
 
+/**
+ * Request address suggestions for a peer
+ *
+ * @param handle the address handle
+ * @param peer the peer id
+ */
 void
 GAS_addresses_request_address (struct GAS_Addresses_Handle *handle,
                                const struct GNUNET_PeerIdentity *peer);
@@ -525,23 +567,37 @@
 /**
  * Cancel address suggestions for a peer
  *
- * @param peer the respective peer
+ * @param handle the address handle
+ * @param peer the peer id
  */
 void
 GAS_addresses_request_address_cancel (struct GAS_Addresses_Handle *handle,
                                       const struct GNUNET_PeerIdentity *peer);
 
 
-
-
 /**
+ * Reset suggestion backoff for a peer
  *
+ * Suggesting addresses is blocked for ATS_BLOCKING_DELTA. Blocking can be
+ * reset using this function
+ *
+ * @param handle the address handle
+ * @param peer the peer id
  */
 void
 GAS_addresses_handle_backoff_reset (struct GAS_Addresses_Handle *handle,
                                     const struct GNUNET_PeerIdentity *peer);
 
 
+/**
+ * Change the preference for a peer
+ *
+ * @param handle the address handle
+ * @param client the client sending this request
+ * @param peer the peer id
+ * @param kind the preference kind to change
+ * @param score the new preference score
+ */
 void
 GAS_addresses_change_preference (struct GAS_Addresses_Handle *handle,
                                  void *client,
@@ -550,13 +606,20 @@
                                  float score);
 
 
-
+/**
+ * Iterator for GAS_addresses_iterate_peers
+ *
+ * @param p_it_cls closure
+ * @param id the peer id
+ */
 typedef void (*GNUNET_ATS_Peer_Iterator) (void *p_it_cls,
                                           const struct GNUNET_PeerIdentity 
*id);
 
+
 /**
  * Return all peers currently known to ATS
  *
+ * @param handle the address handle to use
  * @param p_it the iterator to call for every peer
  * @param p_it_cls the closure for the iterator
  */
@@ -565,20 +628,37 @@
                              GNUNET_ATS_Peer_Iterator p_it,
                              void *p_it_cls);
 
+
+/**
+ * Iterator for GAS_addresses_get_peer_info
+ *
+ * @param p_it_cls closure closure
+ * @param id the peer id
+ * @param plugin_name plugin name
+ * @param plugin_addr address
+ * @param plugin_addr_len address length
+ * @param address_active is address actively used
+ * @param atsi ats performance information
+ * @param atsi_count number of ats performance elements
+ * @param bandwidth_out current outbound bandwidth assigned to address
+ * @param bandwidth_in current inbound bandwidth assigned to address
+ */
 typedef void (*GNUNET_ATS_PeerInfo_Iterator) (void *p_it_cls,
     const struct GNUNET_PeerIdentity *id,
     const char *plugin_name,
-    const void *plugin_addr, size_t plugin_addr_len,
+    const void *plugin_addr,
+    size_t plugin_addr_len,
     const int address_active,
     const struct GNUNET_ATS_Information *atsi,
     uint32_t atsi_count,
-    struct GNUNET_BANDWIDTH_Value32NBO
-    bandwidth_out,
+    struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
     struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in);
 
+
 /**
  * Return information all peers currently known to ATS
  *
+ * @param handle the address handle to use
  * @param peer the respective peer
  * @param pi_it the iterator to call for every peer
  * @param pi_it_cls the closure for the iterator