From 2cc12edbeaaab5ad8181cf84f76035183114b492 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Julius=20B=C3=BCnger?= Date: Thu, 6 Jun 2019 12:30:11 +0200 Subject: [PATCH] TNG testing: Improve comments and logging --- src/transport/test_communicator_unix.c | 55 ++++++++++++++-- src/transport/transport-testing2.c | 70 +++++++++++++++++++-- src/transport/transport-testing2.h | 87 ++++++++++++++++++++++++-- 3 files changed, 195 insertions(+), 17 deletions(-) diff --git a/src/transport/test_communicator_unix.c b/src/transport/test_communicator_unix.c index 459af116a..0fdbe4b99 100644 --- a/src/transport/test_communicator_unix.c +++ b/src/transport/test_communicator_unix.c @@ -85,20 +85,42 @@ add_address_cb (void *cls, } +/** + * @brief Callback that informs whether the requested queue will be + * established + * + * Implements #GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback. + * + * @param cls Closure - unused + * @param tc_h Communicator handle - unused + * @param will_try #GNUNET_YES if queue will be established + * #GNUNET_NO if queue will not be established (bogous address) + */ static void queue_create_reply_cb (void *cls, struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, - int success) + int will_try) { - if (GNUNET_YES == success) + if (GNUNET_YES == will_try) LOG (GNUNET_ERROR_TYPE_DEBUG, - "Got Queue!\n"); + "Queue will be established!\n"); else - LOG (GNUNET_ERROR_TYPE_DEBUG, - "Failed getting queue!\n"); + LOG (GNUNET_ERROR_TYPE_WARNING, + "Queue won't be established (bougus address?)!\n"); } +/** + * @brief Handle opening of queue + * + * Issues sending of test data + * + * Implements #GNUNET_TRANSPORT_TESTING_AddQueueCallback + * + * @param cls Closure + * @param tc_h Communicator handle + * @param tc_queue Handle to newly opened queue + */ static void add_queue_cb (void *cls, struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, @@ -112,6 +134,28 @@ add_queue_cb (void *cls, } +/** + * @brief Handle an incoming message + * + * Implements #GNUNET_TRANSPORT_TESTING_IncomingMessageCallback + + * @param cls Closure + * @param tc_h Handle to the receiving communicator + * @param msg Received message + */ +void +incoming_message_cb (void *cls, + struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, + const struct GNUNET_MessageHeader *msg) +{ +} + + +/** + * @brief Main function called by the scheduler + * + * @param cls Closure - Handle to configuration + */ static void run (void *cls) { @@ -125,6 +169,7 @@ run (void *cls) NULL, &queue_create_reply_cb, &add_queue_cb, + NULL, NULL); /* cls */ tc_hs[1] = GNUNET_TRANSPORT_TESTING_transport_communicator_service_start ( "transport", diff --git a/src/transport/transport-testing2.c b/src/transport/transport-testing2.c index ff8e15719..fc7ae2df6 100644 --- a/src/transport/transport-testing2.c +++ b/src/transport/transport-testing2.c @@ -38,6 +38,9 @@ #define LOG(kind, ...) GNUNET_log_from (kind, "transport-testing2", __VA_ARGS__) +/** + * @brief Handle to a transport communicator + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle { /** @@ -97,12 +100,12 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle char *c_address; /** - * @brief Head of the queues + * @brief Head of the DLL of queues associated with this communicator */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *queue_head; /** - * @brief Tail of the queues + * @brief Tail of the DLL of queues associated with this communicator */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *queue_tail; @@ -128,6 +131,11 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle */ GNUNET_TRANSPORT_TESTING_AddQueueCallback add_queue_cb; + /** + * @brief Callback called when a new communicator connects + */ + GNUNET_TRANSPORT_TESTING_IncomingMessageCallback incoming_msg_cb; + /** * @brief Closure to the callback */ @@ -135,6 +143,9 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle }; +/** + * @brief Queue of a communicator and some context + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue { /** @@ -143,7 +154,11 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h; /** - * @brief Task to request the opening of a view + * @brief Envelope to a message that requests the opening of the queue. + * + * If the client already requests queue(s), but the communicator is not yet + * connected, we cannot send the request to open the queue. Save it until the + * communicator becomes available and send it then. */ struct GNUNET_MQ_Envelope *open_queue_env; @@ -189,6 +204,9 @@ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue }; +/** + * @brief Handle/Context to a single transmission + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission { }; @@ -221,7 +239,9 @@ check_communicator_available ( /** * @brief Handle new communicator * - * @param cls Closure + * Store characteristics of communicator, call respective client callback. + * + * @param cls Closure - communicator handle * @param msg Message struct */ static void @@ -272,6 +292,14 @@ check_add_address (void *cls, } +/** + * @brief The communicator informs about an address. + * + * Store address and call client callback. + * + * @param cls Closure - communicator handle + * @param msg Message + */ static void handle_add_address (void *cls, const struct GNUNET_TRANSPORT_AddAddressMessage *msg) @@ -311,6 +339,15 @@ handle_queue_create_ok (void *cls, } +/** + * @brief Communicator informs that it wont try establishing requested queue. + * + * It will not do so probably because the address is bougus (see comment to + * #GNUNET_MESSAGE_TYPE_TRANSPORT_QUEUE_CREATE_FAIL) + * + * @param cls Closure - communicator handle + * @param msg Message + */ static void handle_queue_create_fail ( void *cls, @@ -342,9 +379,11 @@ check_add_queue_message (void *cls, /** - * @brief Handle new communicator + * @brief Handle new queue * - * @param cls Closure + * Store context and call client callback. + * + * @param cls Closure - communicator handle * @param msg Message struct */ static void @@ -409,10 +448,13 @@ connect_cb (void *cls, if (NULL == tc_h->queue_head) return tc_h; + /* Iterate over queues. They are yet to be opened. Request opening. */ while (NULL != (tc_queue_iter = tc_h->queue_head)) { if (NULL == tc_queue_iter->open_queue_env) continue; + /* Send the previously created mq envelope to request the creation of the + * queue. */ GNUNET_MQ_send (tc_h->c_mq, tc_queue_iter->open_queue_env); tc_queue_iter->open_queue_env = NULL; } @@ -626,6 +668,13 @@ GNUNET_TRANSPORT_TESTING_transport_communicator_service_start ( } +/** + * @brief Instruct communicator to open a queue + * + * @param tc_h Handle to communicator which shall open queue + * @param peer_id Towards which peer + * @param address For which address + */ void GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue ( struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, @@ -670,6 +719,15 @@ GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue ( } +/** + * @brief Instruct communicator to send data + * + * @param tc_queue The queue to use for sending + * @param payload Data to send + * @param payload_size Size of the payload + * + * @return Handle to the transmission + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission * GNUNET_TRANSPORT_TESTING_transport_communicator_send (struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *tc_queue, diff --git a/src/transport/transport-testing2.h b/src/transport/transport-testing2.h index 83d98baab..fbc1927d9 100644 --- a/src/transport/transport-testing2.h +++ b/src/transport/transport-testing2.h @@ -20,7 +20,7 @@ /** * @file transport/transport-testing2.h - * @brief functions related to testing-tng + * @brief functions and structures related to testing-tng * @author Christian Grothoff * @author Julius Bünger */ @@ -30,17 +30,32 @@ #include "transport.h" +/** + * @brief Handle to a transport communicator + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle; + +/** + * @brief Queue of a communicator and some context + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue; + +/** + * @brief Handle/Context to a single transmission + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission; + /** - * @brief Function signature for callbacks that are called when new communicators become available + * @brief Function signature for callbacks that are called when new + * communicators become available * - * @param Closure - * @param msg Message + * @param cls Closure + * @param tc_h Communicator handle + * @param cc Characteristics of communicator + * @param address_prefix Prefix of the address */ typedef void (*GNUNET_TRANSPORT_TESTING_CommunicatorAvailableCallback)(void *cls, @@ -49,6 +64,16 @@ typedef void char *address_prefix); +/** + * @brief Receive information about the address of a communicator. + * + * @param cls Closure + * @param tc_h Communicator handle + * @param address Address represented as string + * @param expiration Expiration + * @param aid Aid + * @param nt Network Type + */ typedef void (*GNUNET_TRANSPORT_TESTING_AddAddressCallback)(void *cls, struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, @@ -58,18 +83,45 @@ typedef void enum GNUNET_NetworkType nt); +/** + * @brief Get informed about the success of a queue request. + * + * @param cls Closure + * @param tc_h Communicator handle + * @param will_try #GNUNET_YES if communicator will try to create queue + */ typedef void (*GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback)(void *cls, struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, int will_try); +/** + * @brief Handle opening of queue + * + * @param cls Closure + * @param tc_h Communicator handle + * @param tc_queue Handle to newly opened queue + */ typedef void (*GNUNET_TRANSPORT_TESTING_AddQueueCallback)(void *cls, struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *tc_queue); +/** + * @brief Handle an incoming message + * + * @param cls Closure + * @param tc_h Handle to the receiving communicator + * @param msg Received message + */ +typedef void +(*GNUNET_TRANSPORT_TESTING_IncomingMessageCallback)(void *cls, + struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, + const struct GNUNET_MessageHeader *msg); + + /** * @brief Start communicator part of transport service and communicator * @@ -77,27 +129,50 @@ typedef void * @param cfg Configuration handle * @param communicator_available Callback that is called when a new * communicator becomes available + * @param add_address_cb Callback handling new addresses + * @param queue_create_reply_cb Callback handling success of queue requests + * @param add_queue_cb Callback handling freshly created queues + * @param incoming_message_cb Callback handling incoming messages * @param cb_cls Closure to @p communicator_available * * @return Handle to the communicator duo */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle * -GNUNET_TRANSPORT_TESTING_transport_communicator_service_start - (const char *service_name, +GNUNET_TRANSPORT_TESTING_transport_communicator_service_start ( + const char *service_name, const char *binary_name, const char *cfg_filename, GNUNET_TRANSPORT_TESTING_CommunicatorAvailableCallback communicator_available_cb, GNUNET_TRANSPORT_TESTING_AddAddressCallback add_address_cb, GNUNET_TRANSPORT_TESTING_QueueCreateReplyCallback queue_create_reply_cb, GNUNET_TRANSPORT_TESTING_AddQueueCallback add_queue_cb, + GNUNET_TRANSPORT_TESTING_IncomingMessageCallback incoming_message_cb, void *cb_cls); + +/** + * @brief Instruct communicator to open a queue + * + * @param tc_h Handle to communicator which shall open queue + * @param peer_id Towards which peer + * @param address For which address + */ void GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue (struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h, const struct GNUNET_PeerIdentity *peer_id, const char *address); + +/** + * @brief Instruct communicator to send data + * + * @param tc_queue The queue to use for sending + * @param payload Data to send + * @param payload_size Size of the payload + * + * @return Handle to the transmission + */ struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorTransmission * GNUNET_TRANSPORT_TESTING_transport_communicator_send (struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorQueue *tc_queue, -- 2.25.1