commit ab500ec36e087619e7e58693dc744c3f67a9d200
parent c7d9b8245a19e203a3a11658038f8e603dad31a3
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 29 Sep 2013 14:29:41 +0000
-minor code/doxygen clean up
Diffstat:
| M | src/dht/dht_api.c | | | 135 | ++++++++++++++++++++++++++++++++++++++++++------------------------------------- |
1 file changed, 71 insertions(+), 64 deletions(-)
diff --git a/src/dht/dht_api.c b/src/dht/dht_api.c
@@ -318,7 +318,7 @@ struct GNUNET_DHT_Handle
/**
* Hash map containing the current outstanding unique GET requests
- * (values are of type 'struct GNUNET_DHT_GetHandle').
+ * (values are of type `struct GNUNET_DHT_GetHandle`).
*/
struct GNUNET_CONTAINER_MultiHashMap *active_requests;
@@ -349,18 +349,19 @@ struct GNUNET_DHT_Handle
* Handler for messages received from the DHT service
* a demultiplexer which handles numerous message types
*
- * @param cls the 'struct GNUNET_DHT_Handle'
+ * @param cls the `struct GNUNET_DHT_Handle`
* @param msg the incoming message
*/
static void
-service_message_handler (void *cls, const struct GNUNET_MessageHeader *msg);
+service_message_handler (void *cls,
+ const struct GNUNET_MessageHeader *msg);
/**
* Try to (re)connect to the DHT service.
*
* @param handle DHT handle to reconnect
- * @return GNUNET_YES on success, GNUNET_NO on failure.
+ * @return #GNUNET_YES on success, #GNUNET_NO on failure.
*/
static int
try_connect (struct GNUNET_DHT_Handle *handle)
@@ -427,13 +428,15 @@ queue_filter_messages (struct GNUNET_DHT_GetHandle *get_handle)
* Add the request corresponding to the given route handle
* to the pending queue (if it is not already in there).
*
- * @param cls the 'struct GNUNET_DHT_Handle*'
+ * @param cls the `struct GNUNET_DHT_Handle *`
* @param key key for the request (not used)
- * @param value the 'struct GNUNET_DHT_GetHandle*'
- * @return GNUNET_YES (always)
+ * @param value the `struct GNUNET_DHT_GetHandle *`
+ * @return #GNUNET_YES (always)
*/
static int
-add_request_to_pending (void *cls, const struct GNUNET_HashCode * key, void *value)
+add_request_to_pending (void *cls,
+ const struct GNUNET_HashCode *key,
+ void *value)
{
struct GNUNET_DHT_Handle *handle = cls;
struct GNUNET_DHT_GetHandle *get_handle = value;
@@ -465,11 +468,12 @@ process_pending_messages (struct GNUNET_DHT_Handle *handle);
/**
* Try reconnecting to the dht service.
*
- * @param cls GNUNET_DHT_Handle
+ * @param cls a `struct GNUNET_DHT_Handle`
* @param tc scheduler context
*/
static void
-try_reconnect (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
+try_reconnect (void *cls,
+ const struct GNUNET_SCHEDULER_TaskContext *tc)
{
struct GNUNET_DHT_Handle *handle = cls;
@@ -533,12 +537,14 @@ do_disconnect (struct GNUNET_DHT_Handle *handle)
* Transmit the next pending message, called by notify_transmit_ready
*
* @param cls the DHT handle
- * @param size number of bytes available in 'buf' for transmission
+ * @param size number of bytes available in @a buf for transmission
* @param buf where to copy messages for the service
- * @return number of bytes written to 'buf'
+ * @return number of bytes written to @a buf
*/
static size_t
-transmit_pending (void *cls, size_t size, void *buf);
+transmit_pending (void *cls,
+ size_t size,
+ void *buf);
/**
@@ -580,12 +586,14 @@ process_pending_messages (struct GNUNET_DHT_Handle *handle)
* Transmit the next pending message, called by notify_transmit_ready
*
* @param cls the DHT handle
- * @param size number of bytes available in 'buf' for transmission
+ * @param size number of bytes available in @a buf for transmission
* @param buf where to copy messages for the service
- * @return number of bytes written to 'buf'
+ * @return number of bytes written to @a buf
*/
static size_t
-transmit_pending (void *cls, size_t size, void *buf)
+transmit_pending (void *cls,
+ size_t size,
+ void *buf)
{
struct GNUNET_DHT_Handle *handle = cls;
struct PendingMessage *head;
@@ -638,14 +646,16 @@ transmit_pending (void *cls, size_t size, void *buf)
* Process a given reply that might match the given
* request.
*
- * @param cls the 'struct GNUNET_DHT_ClientResultMessage'
+ * @param cls the `struct GNUNET_DHT_ClientResultMessage`
* @param key query of the request
- * @param value the 'struct GNUNET_DHT_RouteHandle' of a request matching the same key
- * @return GNUNET_YES to continue to iterate over all results,
- * GNUNET_NO if the reply is malformed or we found a matching request
+ * @param value the `struct GNUNET_DHT_RouteHandle` of a request matching the same key
+ * @return #GNUNET_YES to continue to iterate over all results,
+ * #GNUNET_NO if the reply is malformed or we found a matching request
*/
static int
-process_reply (void *cls, const struct GNUNET_HashCode * key, void *value)
+process_reply (void *cls,
+ const struct GNUNET_HashCode *key,
+ void *value)
{
const struct GNUNET_DHT_ClientResultMessage *dht_msg = cls;
struct GNUNET_DHT_GetHandle *get_handle = value;
@@ -697,8 +707,7 @@ process_reply (void *cls, const struct GNUNET_HashCode * key, void *value)
GNUNET_assert (get_handle->seen_results_end == get_handle->seen_results_transmission_offset);
get_handle->seen_results[get_handle->seen_results_end++] = hc;
/* no need to block it explicitly, service already knows about it! */
- get_handle->seen_results_transmission_offset++;
-
+ get_handle->seen_results_transmission_offset++;
get_handle->iter (get_handle->iter_cls,
GNUNET_TIME_absolute_ntoh (dht_msg->expiration), key,
get_path, get_path_length, put_path, put_path_length,
@@ -706,14 +715,14 @@ process_reply (void *cls, const struct GNUNET_HashCode * key, void *value)
return GNUNET_NO;
}
+
/**
* Process a get monitor message from the service.
*
* @param handle The DHT handle.
* @param msg Monitor get message from the service.
- *
- * @return GNUNET_OK if everything went fine,
- * GNUNET_SYSERR if the message is malformed.
+ * @return #GNUNET_OK if everything went fine,
+ * #GNUNET_SYSERR if the message is malformed.
*/
static int
process_monitor_get_message (struct GNUNET_DHT_Handle *handle,
@@ -748,13 +757,12 @@ process_monitor_get_message (struct GNUNET_DHT_Handle *handle,
*
* @param handle The DHT handle.
* @param msg monitor get response message from the service
- * @return GNUNET_OK if everything went fine,
- * GNUNET_SYSERR if the message is malformed.
+ * @return #GNUNET_OK if everything went fine,
+ * #GNUNET_SYSERR if the message is malformed.
*/
static int
process_monitor_get_resp_message (struct GNUNET_DHT_Handle *handle,
- const struct GNUNET_DHT_MonitorGetRespMessage
- *msg)
+ const struct GNUNET_DHT_MonitorGetRespMessage *msg)
{
struct GNUNET_DHT_MonitorHandle *h;
struct GNUNET_PeerIdentity *path;
@@ -801,9 +809,8 @@ process_monitor_get_resp_message (struct GNUNET_DHT_Handle *handle,
*
* @param handle The DHT handle.
* @param msg Monitor put message from the service.
- *
- * @return GNUNET_OK if everything went fine,
- * GNUNET_SYSERR if the message is malformed.
+ * @return #GNUNET_OK if everything went fine,
+ * #GNUNET_SYSERR if the message is malformed.
*/
static int
process_monitor_put_message (struct GNUNET_DHT_Handle *handle,
@@ -853,8 +860,8 @@ process_monitor_put_message (struct GNUNET_DHT_Handle *handle,
*
* @param handle The DHT handle.
* @param msg confirmation message from the service.
- * @return GNUNET_OK if everything went fine,
- * GNUNET_SYSERR if the message is malformed.
+ * @return #GNUNET_OK if everything went fine,
+ * #GNUNET_SYSERR if the message is malformed.
*/
static int
process_put_confirmation_message (struct GNUNET_DHT_Handle *handle,
@@ -882,7 +889,7 @@ process_put_confirmation_message (struct GNUNET_DHT_Handle *handle,
* Handler for messages received from the DHT service
* a demultiplexer which handles numerous message types
*
- * @param cls the 'struct GNUNET_DHT_Handle'
+ * @param cls the `struct GNUNET_DHT_Handle`
* @param msg the incoming message
*/
static void
@@ -948,9 +955,9 @@ service_message_handler (void *cls, const struct GNUNET_MessageHeader *msg)
"Received reply for `%s' from DHT service %p\n",
GNUNET_h2s (&dht_msg->key), handle);
GNUNET_CONTAINER_multihashmap_get_multiple (handle->active_requests,
- &dht_msg->key,
- &process_reply,
- (void *) dht_msg);
+ &dht_msg->key,
+ &process_reply,
+ (void *) dht_msg);
ret = GNUNET_OK;
break;
case GNUNET_MESSAGE_TYPE_DHT_CLIENT_PUT_OK:
@@ -984,7 +991,6 @@ service_message_handler (void *cls, const struct GNUNET_MessageHeader *msg)
* @param cfg configuration to use
* @param ht_len size of the internal hash table to use for
* processing multiple GET/FIND requests in parallel
- *
* @return handle to the DHT service, or NULL on error
*/
struct GNUNET_DHT_Handle *
@@ -993,7 +999,7 @@ GNUNET_DHT_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
{
struct GNUNET_DHT_Handle *handle;
- handle = GNUNET_malloc (sizeof (struct GNUNET_DHT_Handle));
+ handle = GNUNET_new (struct GNUNET_DHT_Handle);
handle->cfg = cfg;
handle->uid_gen =
GNUNET_CRYPTO_random_u64 (GNUNET_CRYPTO_QUALITY_WEAK, UINT64_MAX);
@@ -1060,11 +1066,12 @@ GNUNET_DHT_disconnect (struct GNUNET_DHT_Handle *handle)
/**
* Timeout for the transmission of a fire&forget-request. Clean it up.
*
- * @param cls the 'struct PendingMessage'
+ * @param cls the `struct GNUNET_DHT_PutHandle *`
* @param tc scheduler context
*/
static void
-timeout_put_request (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
+timeout_put_request (void *cls,
+ const struct GNUNET_SCHEDULER_TaskContext *tc)
{
struct GNUNET_DHT_PutHandle *ph = cls;
struct GNUNET_DHT_Handle *handle = ph->dht_handle;
@@ -1090,7 +1097,7 @@ timeout_put_request (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
* Function called whenever the PUT message leaves the queue. Sets
* the message pointer in the put handle to NULL.
*
- * @param cls the 'struct GNUNET_DHT_PutHandle'
+ * @param cls the `struct GNUNET_DHT_PutHandle`
* @param tc unused
*/
static void
@@ -1121,16 +1128,19 @@ mark_put_message_gone (void *cls,
* @param exp desired expiration time for the value
* @param timeout how long to wait for transmission of this request
* @param cont continuation to call when done (transmitting request to service)
- * You must not call GNUNET_DHT_DISCONNECT in this continuation
- * @param cont_cls closure for cont
+ * You must not call #GNUNET_DHT_disconnect in this continuation
+ * @param cont_cls closure for @a cont
*/
struct GNUNET_DHT_PutHandle *
-GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle, const struct GNUNET_HashCode * key,
+GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle,
+ const struct GNUNET_HashCode * key,
uint32_t desired_replication_level,
enum GNUNET_DHT_RouteOption options,
- enum GNUNET_BLOCK_Type type, size_t size, const void *data,
+ enum GNUNET_BLOCK_Type type, size_t size,
+ const void *data,
struct GNUNET_TIME_Absolute exp,
- struct GNUNET_TIME_Relative timeout, GNUNET_DHT_PutContinuation cont,
+ struct GNUNET_TIME_Relative timeout,
+ GNUNET_DHT_PutContinuation cont,
void *cont_cls)
{
struct GNUNET_DHT_ClientPutMessage *put_msg;
@@ -1145,7 +1155,7 @@ GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle, const struct GNUNET_HashCode *
GNUNET_break (0);
return NULL;
}
- ph = GNUNET_malloc (sizeof (struct GNUNET_DHT_PutHandle));
+ ph = GNUNET_new (struct GNUNET_DHT_PutHandle);
ph->dht_handle = handle;
ph->timeout_task = GNUNET_SCHEDULER_add_delayed (timeout, &timeout_put_request, ph);
ph->cont = cont;
@@ -1185,7 +1195,7 @@ GNUNET_DHT_put (struct GNUNET_DHT_Handle *handle, const struct GNUNET_HashCode *
* has not yet been sent to the service, cancelling the PUT will stop
* this from happening (but there is no way for the user of this API
* to tell if that is the case). The only use for this API is to
- * prevent a later call to 'cont' from "GNUNET_DHT_put" (i.e. because
+ * prevent a later call to 'cont' from #GNUNET_DHT_put (i.e. because
* the system is shutting down).
*
* @param ph put operation to cancel ('cont' will no longer be called)
@@ -1217,7 +1227,7 @@ GNUNET_DHT_put_cancel (struct GNUNET_DHT_PutHandle *ph)
/**
* Perform an asynchronous GET operation on the DHT identified. See
- * also "GNUNET_BLOCK_evaluate".
+ * also #GNUNET_BLOCK_evaluate.
*
* @param handle handle to the DHT service
* @param type expected type of the response object
@@ -1226,7 +1236,7 @@ GNUNET_DHT_put_cancel (struct GNUNET_DHT_PutHandle *ph)
nearest peers this request should reach
* @param options routing options for this message
* @param xquery extended query data (can be NULL, depending on type)
- * @param xquery_size number of bytes in xquery
+ * @param xquery_size number of bytes in @a xquery
* @param iter function to call on each result
* @param iter_cls closure for iter
* @return handle to stop the async get
@@ -1269,7 +1279,7 @@ GNUNET_DHT_get_start (struct GNUNET_DHT_Handle *handle,
GNUNET_CONTAINER_DLL_insert (handle->pending_head, handle->pending_tail,
pending);
pending->in_pending_queue = GNUNET_YES;
- get_handle = GNUNET_malloc (sizeof (struct GNUNET_DHT_GetHandle));
+ get_handle = GNUNET_new (struct GNUNET_DHT_GetHandle);
get_handle->dht_handle = handle;
get_handle->iter = iter;
get_handle->iter_cls = iter_cls;
@@ -1282,14 +1292,13 @@ GNUNET_DHT_get_start (struct GNUNET_DHT_Handle *handle,
}
-
/**
* Tell the DHT not to return any of the following known results
* to this client.
*
* @param get_handle get operation for which results should be filtered
* @param num_results number of results to be blocked that are
- * provided in this call (size of the 'results' array)
+ * provided in this call (size of the @a results array)
* @param results array of hash codes over the 'data' of the results
* to be blocked
*/
@@ -1330,7 +1339,8 @@ GNUNET_DHT_get_stop (struct GNUNET_DHT_GetHandle *get_handle)
handle = get_handle->message->handle;
get_msg =
(const struct GNUNET_DHT_ClientGetMessage *) get_handle->message->msg;
- LOG (GNUNET_ERROR_TYPE_DEBUG, "Sending STOP for %s to DHT via %p\n",
+ LOG (GNUNET_ERROR_TYPE_DEBUG,
+ "Sending STOP for %s to DHT via %p\n",
GNUNET_h2s (&get_msg->key), handle);
/* generate STOP */
pending =
@@ -1379,8 +1389,7 @@ GNUNET_DHT_get_stop (struct GNUNET_DHT_GetHandle *get_handle)
* @param get_cb Callback to process monitored get messages.
* @param get_resp_cb Callback to process monitored get response messages.
* @param put_cb Callback to process monitored put messages.
- * @param cb_cls Closure for cb.
- *
+ * @param cb_cls Closure for callbacks.
* @return Handle to stop monitoring.
*/
struct GNUNET_DHT_MonitorHandle *
@@ -1396,7 +1405,7 @@ GNUNET_DHT_monitor_start (struct GNUNET_DHT_Handle *handle,
struct GNUNET_DHT_MonitorStartStopMessage *m;
struct PendingMessage *pending;
- h = GNUNET_malloc (sizeof (struct GNUNET_DHT_MonitorHandle));
+ h = GNUNET_new (struct GNUNET_DHT_MonitorHandle);
GNUNET_CONTAINER_DLL_insert(handle->monitor_head, handle->monitor_tail, h);
h->get_cb = get_cb;
@@ -1407,8 +1416,8 @@ GNUNET_DHT_monitor_start (struct GNUNET_DHT_Handle *handle,
h->dht_handle = handle;
if (NULL != key)
{
- h->key = GNUNET_malloc (sizeof(struct GNUNET_HashCode));
- memcpy (h->key, key, sizeof(struct GNUNET_HashCode));
+ h->key = GNUNET_new(struct GNUNET_HashCode);
+ h->key = *key;
}
pending = GNUNET_malloc (sizeof (struct GNUNET_DHT_MonitorStartStopMessage) +
@@ -1479,6 +1488,4 @@ GNUNET_DHT_monitor_stop (struct GNUNET_DHT_MonitorHandle *handle)
GNUNET_free (handle);
}
-
-
/* end of dht_api.c */
