statistics.rst (6293B)
1 2 .. index:: 3 double: STATISTICS; subsystem 4 5 .. _STATISTICS-Subsystem-Dev: 6 7 STATISTICS 8 ========== 9 10 **libgnunetstatistics** is the library containing the API for the 11 STATISTICS subsystem. Any process requiring to use STATISTICS should use 12 this API by to open a connection to the STATISTICS service. This is done 13 by calling the function ``GNUNET_STATISTICS_create()``. This function 14 takes the subsystem's name which is trying to use STATISTICS and a 15 configuration. All values written to STATISTICS with this connection 16 will be placed in the section corresponding to the given subsystem's 17 name. The connection to STATISTICS can be destroyed with the function 18 ``GNUNET_STATISTICS_destroy()``. This function allows for the connection 19 to be destroyed immediately or upon transferring all pending write 20 requests to the service. 21 22 Note: STATISTICS subsystem can be disabled by setting ``DISABLE = YES`` 23 under the ``[STATISTICS]`` section in the configuration. With such a 24 configuration all calls to ``GNUNET_STATISTICS_create()`` return 25 ``NULL`` as the STATISTICS subsystem is unavailable and no other 26 functions from the API can be used. 27 28 .. _Statistics-retrieval: 29 30 Statistics retrieval 31 ^^^^^^^^^^^^^^^^^^^^ 32 33 Once a connection to the statistics service is obtained, information 34 about any other system which uses statistics can be retrieved with the 35 function GNUNET_STATISTICS_get(). This function takes the connection 36 handle, the name of the subsystem whose information we are interested in 37 (a ``NULL`` value will retrieve information of all available subsystems 38 using STATISTICS), the name of the statistic we are interested in (a 39 ``NULL`` value will retrieve all available statistics), a continuation 40 callback which is called when all of requested information is retrieved, 41 an iterator callback which is called for each parameter in the retrieved 42 information and a closure for the aforementioned callbacks. The library 43 then invokes the iterator callback for each value matching the request. 44 45 Call to ``GNUNET_STATISTICS_get()`` is asynchronous and can be canceled 46 with the function ``GNUNET_STATISTICS_get_cancel()``. This is helpful 47 when retrieving statistics takes too long and especially when we want to 48 shutdown and cleanup everything. 49 50 .. _Setting-statistics-and-updating-them: 51 52 Setting statistics and updating them 53 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 54 55 So far we have seen how to retrieve statistics, here we will learn how 56 we can set statistics and update them so that other subsystems can 57 retrieve them. 58 59 A new statistic can be set using the function 60 ``GNUNET_STATISTICS_set()``. This function takes the name of the 61 statistic and its value and a flag to make the statistic persistent. The 62 value of the statistic should be of the type ``uint64_t``. The function 63 does not take the name of the subsystem; it is determined from the 64 previous ``GNUNET_STATISTICS_create()`` invocation. If the given 65 statistic is already present, its value is overwritten. 66 67 An existing statistics can be updated, i.e its value can be increased or 68 decreased by an amount with the function ``GNUNET_STATISTICS_update()``. 69 The parameters to this function are similar to 70 ``GNUNET_STATISTICS_set()``, except that it takes the amount to be 71 changed as a type ``int64_t`` instead of the value. 72 73 The library will combine multiple set or update operations into one 74 message if the client performs requests at a rate that is faster than 75 the available IPC with the STATISTICS service. Thus, the client does not 76 have to worry about sending requests too quickly. 77 78 .. _Watches: 79 80 Watches 81 ^^^^^^^ 82 83 As interesting feature of STATISTICS lies in serving notifications 84 whenever a statistic of our interest is modified. This is achieved by 85 registering a watch through the function ``GNUNET_STATISTICS_watch()``. 86 The parameters of this function are similar to those of 87 ``GNUNET_STATISTICS_get()``. Changes to the respective statistic's value 88 will then cause the given iterator callback to be called. Note: A watch 89 can only be registered for a specific statistic. Hence the subsystem 90 name and the parameter name cannot be ``NULL`` in a call to 91 ``GNUNET_STATISTICS_watch()``. 92 93 A registered watch will keep notifying any value changes until 94 ``GNUNET_STATISTICS_watch_cancel()`` is called with the same parameters 95 that are used for registering the watch. 96 97 .. _The-STATISTICS-Client_002dService-Protocol: 98 99 The STATISTICS Client-Service Protocol 100 -------------------------------------- 101 102 .. _Statistics-retrieval2: 103 104 Statistics retrieval 105 ^^^^^^^^^^^^^^^^^^^^ 106 107 To retrieve statistics, the client transmits a message of type 108 ``GNUNET_MESSAGE_TYPE_STATISTICS_GET`` containing the given subsystem 109 name and statistic parameter to the STATISTICS service. The service 110 responds with a message of type ``GNUNET_MESSAGE_TYPE_STATISTICS_VALUE`` 111 for each of the statistics parameters that match the client request for 112 the client. The end of information retrieved is signaled by the service 113 by sending a message of type ``GNUNET_MESSAGE_TYPE_STATISTICS_END``. 114 115 .. _Setting-and-updating-statistics: 116 117 Setting and updating statistics 118 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 119 120 The subsystem name, parameter name, its value and the persistence flag 121 are communicated to the service through the message 122 ``GNUNET_MESSAGE_TYPE_STATISTICS_SET``. 123 124 When the service receives a message of type 125 ``GNUNET_MESSAGE_TYPE_STATISTICS_SET``, it retrieves the subsystem name 126 and checks for a statistic parameter with matching the name given in the 127 message. If a statistic parameter is found, the value is overwritten by 128 the new value from the message; if not found then a new statistic 129 parameter is created with the given name and value. 130 131 In addition to just setting an absolute value, it is possible to perform 132 a relative update by sending a message of type 133 ``GNUNET_MESSAGE_TYPE_STATISTICS_SET`` with an update flag 134 (``GNUNET_STATISTICS_SETFLAG_RELATIVE``) signifying that the value in 135 the message should be treated as an update value. 136 137 .. _Watching-for-updates: 138 139 Watching for updates 140 ^^^^^^^^^^^^^^^^^^^^ 141 142 The function registers the watch at the service by sending a message of 143 type ``GNUNET_MESSAGE_TYPE_STATISTICS_WATCH``. The service then sends 144 notifications through messages of type 145 ``GNUNET_MESSAGE_TYPE_STATISTICS_WATCH_VALUE`` whenever the statistic 146 parameter's value is changed. 147 148