diff options
author | ng0 <ng0@infotropique.org> | 2017-10-19 15:19:32 +0000 |
---|---|---|
committer | ng0 <ng0@infotropique.org> | 2017-10-19 15:19:32 +0000 |
commit | 07e671228bea1e23ea07dedc3ce2eec049279871 (patch) | |
tree | 384380dcc3a33b706effaf60495955fbe8470297 /doc/chapters | |
parent | fa780739b3ec7d22a98407797f20f2015f9190de (diff) | |
download | gnunet-07e671228bea1e23ea07dedc3ce2eec049279871.tar.gz gnunet-07e671228bea1e23ea07dedc3ce2eec049279871.zip |
chapters/developer.texi: line length 74 for the first 19% of the file.
Diffstat (limited to 'doc/chapters')
-rw-r--r-- | doc/chapters/developer.texi | 1463 |
1 files changed, 770 insertions, 693 deletions
diff --git a/doc/chapters/developer.texi b/doc/chapters/developer.texi index da8aa8a83..9a58e38cc 100644 --- a/doc/chapters/developer.texi +++ b/doc/chapters/developer.texi | |||
@@ -1,4 +1,4 @@ | |||
1 | @c *************************************************************************** | 1 | @c *********************************************************************** |
2 | @node GNUnet Developer Handbook | 2 | @node GNUnet Developer Handbook |
3 | @chapter GNUnet Developer Handbook | 3 | @chapter GNUnet Developer Handbook |
4 | 4 | ||
@@ -12,39 +12,40 @@ that believes in the GNU philosophy | |||
12 | @item | 12 | @item |
13 | A set of standards, including coding conventions and architectural rules | 13 | A set of standards, including coding conventions and architectural rules |
14 | @item | 14 | @item |
15 | A set of layered protocols, both specifying the communication between peers as | 15 | A set of layered protocols, both specifying the communication between |
16 | well as the communication between components of a single peer. | 16 | peers as well as the communication between components of a single peer. |
17 | @item | 17 | @item |
18 | A set of libraries with well-defined APIs suitable for writing extensions | 18 | A set of libraries with well-defined APIs suitable for writing extensions |
19 | @end itemize | 19 | @end itemize |
20 | 20 | ||
21 | In particular, the architecture specifies that a peer consists of many | 21 | In particular, the architecture specifies that a peer consists of many |
22 | processes communicating via protocols. Processes can be written in almost | 22 | processes communicating via protocols. Processes can be written in almost |
23 | any language. C and Java APIs exist for accessing existing services and for | 23 | any language. C and Java APIs exist for accessing existing services and |
24 | writing extensions. It is possible to write extensions in other languages by | 24 | for writing extensions. It is possible to write extensions in other |
25 | implementing the necessary IPC protocols. | 25 | languages by implementing the necessary IPC protocols. |
26 | 26 | ||
27 | GNUnet can be extended and improved along many possible dimensions, and anyone | 27 | GNUnet can be extended and improved along many possible dimensions, and |
28 | interested in free software and freedom-enhancing networking is welcome to | 28 | anyone interested in free software and freedom-enhancing networking is |
29 | join the effort. This developer handbook attempts to provide an initial | 29 | welcome to join the effort. This developer handbook attempts to provide |
30 | introduction to some of the key design choices and central components of the | 30 | an initial introduction to some of the key design choices and central |
31 | system. This manual is far from complete, and we welcome informed | 31 | components of the system. This manual is far from complete, and we |
32 | contributions, be it in the form of new chapters or insightful comments. | 32 | welcome informed contributions, be it in the form of new chapters or |
33 | insightful comments. | ||
33 | 34 | ||
34 | However, the website is experiencing a constant onslaught of sophisticated | 35 | However, the website is experiencing a constant onslaught of sophisticated |
35 | link-spam entered manually by exploited workers solving puzzles and | 36 | link-spam entered manually by exploited workers solving puzzles and |
36 | customizing text. To limit this commercial defacement, we are strictly | 37 | customizing text. To limit this commercial defacement, we are strictly |
37 | moderating comments and have disallowed "normal" users from posting new | 38 | moderating comments and have disallowed "normal" users from posting new |
38 | content. However, this is really only intended to keep the spam at bay. If | 39 | content. However, this is really only intended to keep the spam at bay. If |
39 | you are a real user or aspiring developer, please drop us a note (IRC, e-mail, | 40 | you are a real user or aspiring developer, please drop us a note |
40 | contact form) with your user profile ID number included. We will then relax | 41 | (IRC, e-mail, contact form) with your user profile ID number included. |
41 | these restrictions on your account. We're sorry for this inconvenience; | 42 | We will then relax these restrictions on your account. We're sorry for |
42 | however, few people would want to read this site if 99% of it was | 43 | this inconvenience; however, few people would want to read this site |
43 | advertisements for bogus websites. | 44 | if 99% of it was advertisements for bogus websites. |
44 | 45 | ||
45 | 46 | ||
46 | 47 | ||
47 | @c *************************************************************************** | 48 | @c *********************************************************************** |
48 | 49 | ||
49 | 50 | ||
50 | 51 | ||
@@ -95,15 +96,16 @@ advertisements for bogus websites. | |||
95 | @node Developer Introduction | 96 | @node Developer Introduction |
96 | @section Developer Introduction | 97 | @section Developer Introduction |
97 | 98 | ||
98 | This developer handbook is intended as first introduction to GNUnet for new | 99 | This developer handbook is intended as first introduction to GNUnet for |
99 | developers that want to extend the GNUnet framework. After the introduction, | 100 | new developers that want to extend the GNUnet framework. After the |
100 | each of the GNUnet subsystems (directories in the @file{src/} tree) is (supposed to | 101 | introduction, each of the GNUnet subsystems (directories in the |
101 | be) covered in its own chapter. In addition to this documentation, GNUnet | 102 | @file{src/} tree) is (supposed to be) covered in its own chapter. In |
102 | developers should be aware of the services available on the GNUnet server to | 103 | addition to this documentation, GNUnet developers should be aware of the |
103 | them. | 104 | services available on the GNUnet server to them. |
104 | 105 | ||
105 | New developers can have a look a the GNUnet tutorials for C and java available | 106 | New developers can have a look a the GNUnet tutorials for C and java |
106 | in the @file{src/} directory of the repository or under the following links: | 107 | available in the @file{src/} directory of the repository or under the |
108 | following links: | ||
107 | 109 | ||
108 | @c ** FIXME: Link to files in source, not online. | 110 | @c ** FIXME: Link to files in source, not online. |
109 | @c ** FIXME: Where is the Java tutorial? | 111 | @c ** FIXME: Where is the Java tutorial? |
@@ -114,45 +116,47 @@ in the @file{src/} directory of the repository or under the following links: | |||
114 | 116 | ||
115 | In addition to this book, the GNUnet server contains various resources for | 117 | In addition to this book, the GNUnet server contains various resources for |
116 | GNUnet developers. They are all conveniently reachable via the "Developer" | 118 | GNUnet developers. They are all conveniently reachable via the "Developer" |
117 | entry in the navigation menu. Some additional tools (such as static analysis | 119 | entry in the navigation menu. Some additional tools (such as static |
118 | reports) require a special developer access to perform certain operations. If | 120 | analysis reports) require a special developer access to perform certain |
119 | you feel you need access, you should contact | 121 | operations. If you feel you need access, you should contact |
120 | @uref{http://grothoff.org/christian/, Christian Grothoff}, GNUnet's maintainer. | 122 | @uref{http://grothoff.org/christian/, Christian Grothoff}, |
123 | GNUnet's maintainer. | ||
121 | 124 | ||
122 | The public subsystems on the GNUnet server that help developers are: | 125 | The public subsystems on the GNUnet server that help developers are: |
123 | 126 | ||
124 | @itemize @bullet | 127 | @itemize @bullet |
125 | @item The Version control system keeps our code and enables distributed | 128 | @item The Version control system keeps our code and enables distributed |
126 | development. Only developers with write access can commit code, everyone else | 129 | development. Only developers with write access can commit code, everyone |
127 | is encouraged to submit patches to the | 130 | else is encouraged to submit patches to the |
128 | @uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, GNUnet-developers mailinglist}. | 131 | @uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, GNUnet-developers mailinglist}. |
129 | @item The GNUnet bugtracking system is used to track feature requests, open bug | 132 | @item The GNUnet bugtracking system is used to track feature requests, |
130 | reports and their resolutions. Anyone can report bugs, only developers can | 133 | open bug reports and their resolutions. Anyone can report bugs, only |
131 | claim to have fixed them. | 134 | developers can claim to have fixed them. |
132 | @item A buildbot is used to check GNUnet builds automatically on a range of | 135 | @item A buildbot is used to check GNUnet builds automatically on a range |
133 | platforms. Builds are triggered automatically after 30 minutes of no changes to | 136 | of platforms. Builds are triggered automatically after 30 minutes of no |
134 | Git. | 137 | changes to Git. |
135 | @item The current quality of our automated test suite is assessed using Code | 138 | @item The current quality of our automated test suite is assessed using |
136 | coverage analysis. This analysis is run daily; however the webpage is only | 139 | Code coverage analysis. This analysis is run daily; however the webpage |
137 | updated if all automated tests pass at that time. Testcases that improve our | 140 | is only updated if all automated tests pass at that time. Testcases that |
138 | code coverage are always welcome. | 141 | improve our code coverage are always welcome. |
139 | @item We try to automatically find bugs using a static analysis scan. This scan | 142 | @item We try to automatically find bugs using a static analysis scan. |
140 | is run daily; however the webpage is only updated if all automated tests pass | 143 | This scan is run daily; however the webpage is only updated if all |
141 | at the time. Note that not everything that is flagged by the analysis is a bug, | 144 | automated tests pass at the time. Note that not everything that is |
142 | sometimes even good code can be marked as possibly problematic. Nevertheless, | 145 | flagged by the analysis is a bug, sometimes even good code can be marked |
143 | developers are encouraged to at least be aware of all issues in their code that | 146 | as possibly problematic. Nevertheless, developers are encouraged to at |
144 | are listed. | 147 | least be aware of all issues in their code that are listed. |
145 | @item We use Gauger for automatic performance regression visualization. Details | 148 | @item We use Gauger for automatic performance regression visualization. |
146 | on how to use Gauger are here. | 149 | Details on how to use Gauger are here. |
147 | @item We use @uref{http://junit.org/, junit} to automatically test gnunet-java. | 150 | @item We use @uref{http://junit.org/, junit} to automatically test |
148 | Automatically generated, current reports on the test suite are here. | 151 | gnunet-java. Automatically generated, current reports on the test suite |
152 | are here. | ||
149 | @item We use Cobertura to generate test coverage reports for gnunet-java. | 153 | @item We use Cobertura to generate test coverage reports for gnunet-java. |
150 | Current reports on test coverage are here. | 154 | Current reports on test coverage are here. |
151 | @end itemize | 155 | @end itemize |
152 | 156 | ||
153 | 157 | ||
154 | 158 | ||
155 | @c *************************************************************************** | 159 | @c *********************************************************************** |
156 | @menu | 160 | @menu |
157 | * Project overview:: | 161 | * Project overview:: |
158 | @end menu | 162 | @end menu |
@@ -160,10 +164,11 @@ Current reports on test coverage are here. | |||
160 | @node Project overview | 164 | @node Project overview |
161 | @subsection Project overview | 165 | @subsection Project overview |
162 | 166 | ||
163 | The GNUnet project consists at this point of several sub-projects. This section | 167 | The GNUnet project consists at this point of several sub-projects. This |
164 | is supposed to give an initial overview about the various sub-projects. Note | 168 | section is supposed to give an initial overview about the various |
165 | that this description also lists projects that are far from complete, including | 169 | sub-projects. Note that this description also lists projects that are far |
166 | even those that have literally not a single line of code in them yet. | 170 | from complete, including even those that have literally not a single line |
171 | of code in them yet. | ||
167 | 172 | ||
168 | GNUnet sub-projects in order of likely relevance are currently: | 173 | GNUnet sub-projects in order of likely relevance are currently: |
169 | 174 | ||
@@ -173,14 +178,17 @@ GNUnet sub-projects in order of likely relevance are currently: | |||
173 | chat applications; this is what the developer handbook covers mostly | 178 | chat applications; this is what the developer handbook covers mostly |
174 | @item gnunet-gtk Gtk+-based user interfaces, including gnunet-fs-gtk | 179 | @item gnunet-gtk Gtk+-based user interfaces, including gnunet-fs-gtk |
175 | (file-sharing), gnunet-statistics-gtk (statistics over time), | 180 | (file-sharing), gnunet-statistics-gtk (statistics over time), |
176 | gnunet-peerinfo-gtk (information about current connections and known peers), | 181 | gnunet-peerinfo-gtk (information about current connections and known |
177 | gnunet-chat-gtk (chat GUI) and gnunet-setup (setup tool for "everything") | 182 | peers), gnunet-chat-gtk (chat GUI) and gnunet-setup (setup tool for |
178 | @item gnunet-fuse Mounting directories shared via GNUnet's file-sharing on Linux | 183 | "everything") |
184 | @item gnunet-fuse Mounting directories shared via GNUnet's file-sharing | ||
185 | on Linux | ||
179 | @item gnunet-update Installation and update tool | 186 | @item gnunet-update Installation and update tool |
180 | @item gnunet-ext Template for starting 'external' GNUnet projects | 187 | @item gnunet-ext Template for starting 'external' GNUnet projects |
181 | @item gnunet-java Java APIs for writing GNUnet services and applications | 188 | @item gnunet-java Java APIs for writing GNUnet services and applications |
182 | @c ** FIXME: Point to new website repository once we have it: | 189 | @c ** FIXME: Point to new website repository once we have it: |
183 | @c ** @item svn/gnunet-www/ Code and media helping drive the GNUnet website | 190 | @c ** @item svn/gnunet-www/ Code and media helping drive the GNUnet |
191 | website | ||
184 | @item eclectic Code to run | 192 | @item eclectic Code to run |
185 | GNUnet nodes on testbeds for research, development, testing and evaluation | 193 | GNUnet nodes on testbeds for research, development, testing and evaluation |
186 | @c ** FIXME: Solve the status and location of gnunet-qt | 194 | @c ** FIXME: Solve the status and location of gnunet-qt |
@@ -197,253 +205,266 @@ We are also working on various supporting libraries and tools: | |||
197 | @item libmicrohttpd GNU libmicrohttpd (embedded HTTP(S) server library) | 205 | @item libmicrohttpd GNU libmicrohttpd (embedded HTTP(S) server library) |
198 | @item gauger Tool for performance regression analysis | 206 | @item gauger Tool for performance regression analysis |
199 | @item monkey Tool for automated debugging of distributed systems | 207 | @item monkey Tool for automated debugging of distributed systems |
200 | @item libmwmodem Library for accessing satellite connection quality reports | 208 | @item libmwmodem Library for accessing satellite connection quality |
209 | reports | ||
201 | @end table | 210 | @end table |
202 | 211 | ||
203 | Finally, there are various external projects (see links for a list of those | 212 | Finally, there are various external projects (see links for a list of |
204 | that have a public website) which build on top of the GNUnet framework. | 213 | those that have a public website) which build on top of the GNUnet |
214 | framework. | ||
205 | 215 | ||
206 | @c *************************************************************************** | 216 | @c *********************************************************************** |
207 | @node Code overview | 217 | @node Code overview |
208 | @section Code overview | 218 | @section Code overview |
209 | 219 | ||
210 | This section gives a brief overview of the GNUnet source code. Specifically, we | 220 | This section gives a brief overview of the GNUnet source code. |
211 | sketch the function of each of the subdirectories in the @file{gnunet/src/} | 221 | Specifically, we sketch the function of each of the subdirectories in |
212 | directory. The order given is roughly bottom-up (in terms of the layers of the | 222 | the @file{gnunet/src/} directory. The order given is roughly bottom-up |
213 | system). | 223 | (in terms of the layers of the system). |
214 | @table @asis | ||
215 | 224 | ||
225 | @table @asis | ||
216 | @item util/ --- libgnunetutil Library with general utility functions, all | 226 | @item util/ --- libgnunetutil Library with general utility functions, all |
217 | GNUnet binaries link against this library. Anything from memory allocation and | 227 | GNUnet binaries link against this library. Anything from memory |
218 | data structures to cryptography and inter-process communication. The goal is to | 228 | allocation and data structures to cryptography and inter-process |
219 | provide an OS-independent interface and more 'secure' or convenient | 229 | communication. The goal is to provide an OS-independent interface and |
220 | implementations of commonly used primitives. The API is spread over more than a | 230 | more 'secure' or convenient implementations of commonly used primitives. |
221 | dozen headers, developers should study those closely to avoid duplicating | 231 | The API is spread over more than a dozen headers, developers should study |
222 | existing functions. | 232 | those closely to avoid duplicating existing functions. |
223 | @item hello/ --- libgnunethello HELLO messages are used to | 233 | @item hello/ --- libgnunethello HELLO messages are used to |
224 | describe under which addresses a peer can be reached (for example, protocol, | 234 | describe under which addresses a peer can be reached (for example, |
225 | IP, port). This library manages parsing and generating of HELLO messages. | 235 | protocol, IP, port). This library manages parsing and generating of HELLO |
226 | @item block/ --- libgnunetblock The DHT and other components of GNUnet store | 236 | messages. |
227 | information in units called 'blocks'. Each block has a type and the type | 237 | @item block/ --- libgnunetblock The DHT and other components of GNUnet |
228 | defines a particular format and how that binary format is to be linked to a | 238 | store information in units called 'blocks'. Each block has a type and the |
229 | hash code (the key for the DHT and for databases). The block library is a | 239 | type defines a particular format and how that binary format is to be |
230 | wapper around block plugins which provide the necessary functions for each | 240 | linked to a hash code (the key for the DHT and for databases). The block |
231 | block type. | 241 | library is a wapper around block plugins which provide the necessary |
242 | functions for each block type. | ||
232 | @item statistics/ The statistics service enables associating | 243 | @item statistics/ The statistics service enables associating |
233 | values (of type uint64_t) with a componenet name and a string. The main uses is | 244 | values (of type uint64_t) with a componenet name and a string. The main |
234 | debugging (counting events), performance tracking and user entertainment (what | 245 | uses is debugging (counting events), performance tracking and user |
235 | did my peer do today?). | 246 | entertainment (what did my peer do today?). |
236 | @item arm/ The automatic-restart-manager (ARM) service | 247 | @item arm/ The automatic-restart-manager (ARM) service |
237 | is the GNUnet master service. Its role is to start gnunet-services, to re-start | 248 | is the GNUnet master service. Its role is to start gnunet-services, to |
238 | them when they crashed and finally to shut down the system when requested. | 249 | re-start them when they crashed and finally to shut down the system when |
239 | @item peerinfo/ The peerinfo service keeps track of which peers are known to | 250 | requested. |
240 | the local peer and also tracks the validated addresses for each peer (in the | 251 | @item peerinfo/ The peerinfo service keeps track of which peers are known |
241 | form of a HELLO message) for each of those peers. The peer is not necessarily | 252 | to the local peer and also tracks the validated addresses for each peer |
242 | connected to all peers known to the peerinfo service. Peerinfo provides | 253 | (in the form of a HELLO message) for each of those peers. The peer is not |
243 | persistent storage for peer identities --- peers are not forgotten just because | 254 | necessarily connected to all peers known to the peerinfo service. |
244 | of a system restart. | 255 | Peerinfo provides persistent storage for peer identities --- peers are |
256 | not forgotten just because of a system restart. | ||
245 | @item datacache/ --- libgnunetdatacache The datacache | 257 | @item datacache/ --- libgnunetdatacache The datacache |
246 | library provides (temporary) block storage for the DHT. Existing plugins can | 258 | library provides (temporary) block storage for the DHT. Existing plugins |
247 | store blocks in Sqlite, Postgres or MySQL databases. All data stored in the | 259 | can store blocks in Sqlite, Postgres or MySQL databases. All data stored |
248 | cache is lost when the peer is stopped or restarted (datacache uses temporary | 260 | in the cache is lost when the peer is stopped or restarted (datacache |
249 | tables). | 261 | uses temporary tables). |
250 | @item datastore/ The datastore service stores file-sharing blocks in | 262 | @item datastore/ The datastore service stores file-sharing blocks in |
251 | databases for extended periods of time. In contrast to the datacache, data is | 263 | databases for extended periods of time. In contrast to the datacache, data |
252 | not lost when peers restart. However, quota restrictions may still cause old, | 264 | is not lost when peers restart. However, quota restrictions may still |
253 | expired or low-priority data to be eventually discarded. Existing plugins can | 265 | cause old, expired or low-priority data to be eventually discarded. |
254 | store blocks in Sqlite, Postgres or MySQL databases. | 266 | Existing plugins can store blocks in Sqlite, Postgres or MySQL databases. |
255 | @item template/ Template | 267 | @item template/ Template for writing a new service. Does nothing. |
256 | for writing a new service. Does nothing. | ||
257 | @item ats/ The automatic transport | 268 | @item ats/ The automatic transport |
258 | selection (ATS) service is responsible for deciding which address (i.e. which | 269 | selection (ATS) service is responsible for deciding which address (i.e. |
259 | transport plugin) should be used for communication with other peers, and at | 270 | which transport plugin) should be used for communication with other peers, |
260 | what bandwidth. | 271 | and at what bandwidth. |
261 | @item nat/ --- libgnunetnat Library that provides basic | 272 | @item nat/ --- libgnunetnat Library that provides basic |
262 | functions for NAT traversal. The library supports NAT traversal with manual | 273 | functions for NAT traversal. The library supports NAT traversal with |
263 | hole-punching by the user, UPnP and ICMP-based autonomous NAT traversal. The | 274 | manual hole-punching by the user, UPnP and ICMP-based autonomous NAT |
264 | library also includes an API for testing if the current configuration works and | 275 | traversal. The library also includes an API for testing if the current |
265 | the @code{gnunet-nat-server} which provides an external service to test the | 276 | configuration works and the @code{gnunet-nat-server} which provides an |
266 | local configuration. | 277 | external service to test the local configuration. |
267 | @item fragmentation/ --- libgnunetfragmentation Some | 278 | @item fragmentation/ --- libgnunetfragmentation Some |
268 | transports (UDP and WLAN, mostly) have restrictions on the maximum transfer | 279 | transports (UDP and WLAN, mostly) have restrictions on the maximum |
269 | unit (MTU) for packets. The fragmentation library can be used to break larger | 280 | transfer unit (MTU) for packets. The fragmentation library can be used to |
270 | packets into chunks of at most 1k and transmit the resulting fragments | 281 | break larger packets into chunks of at most 1k and transmit the resulting |
271 | reliabily (with acknowledgement, retransmission, timeouts, etc.). | 282 | fragments reliabily (with acknowledgement, retransmission, timeouts, |
272 | @item transport/ The transport service is responsible for managing the basic P2P | 283 | etc.). |
273 | communication. It uses plugins to support P2P communication over TCP, UDP, | 284 | @item transport/ The transport service is responsible for managing the |
274 | HTTP, HTTPS and other protocols.The transport service validates peer addresses, | 285 | basic P2P communication. It uses plugins to support P2P communication |
275 | enforces bandwidth restrictions, limits the total number of connections and | 286 | over TCP, UDP, HTTP, HTTPS and other protocols.The transport service |
276 | enforces connectivity restrictions (i.e. friends-only). | 287 | validates peer addresses, enforces bandwidth restrictions, limits the |
288 | total number of connections and enforces connectivity restrictions (i.e. | ||
289 | friends-only). | ||
277 | @item peerinfo-tool/ | 290 | @item peerinfo-tool/ |
278 | This directory contains the gnunet-peerinfo binary which can be used to inspect | 291 | This directory contains the gnunet-peerinfo binary which can be used to |
279 | the peers and HELLOs known to the peerinfo service. | 292 | inspect the peers and HELLOs known to the peerinfo service. |
280 | @item core/ The core | 293 | @item core/ The core |
281 | service is responsible for establishing encrypted, authenticated connections | 294 | service is responsible for establishing encrypted, authenticated |
282 | with other peers, encrypting and decrypting messages and forwarding messages to | 295 | connections with other peers, encrypting and decrypting messages and |
283 | higher-level services that are interested in them. | 296 | forwarding messages to higher-level services that are interested in them. |
284 | @item testing/ --- | 297 | @item testing/ --- |
285 | libgnunettesting The testing library allows starting (and stopping) peers for | 298 | libgnunettesting The testing library allows starting (and stopping) peers |
286 | writing testcases.@ | 299 | for writing testcases.@ |
287 | It also supports automatic generation of configurations for | 300 | It also supports automatic generation of configurations for peers |
288 | peers ensuring that the ports and paths are disjoint. libgnunettesting is also | 301 | ensuring that the ports and paths are disjoint. libgnunettesting is also |
289 | the foundation for the testbed service | 302 | the foundation for the testbed service |
290 | @item testbed/ The testbed service is | 303 | @item testbed/ The testbed service is |
291 | used for creating small or large scale deployments of GNUnet peers for | 304 | used for creating small or large scale deployments of GNUnet peers for |
292 | evaluation of protocols. It facilitates peer depolyments on multiple hosts (for | 305 | evaluation of protocols. It facilitates peer depolyments on multiple |
293 | example, in a cluster) and establishing varous network topologies (both | 306 | hosts (for example, in a cluster) and establishing varous network |
294 | underlay and overlay). | 307 | topologies (both underlay and overlay). |
295 | @item nse/ The network size estimation (NSE) service | 308 | @item nse/ The network size estimation (NSE) service |
296 | implements a protocol for (securely) estimating the current size of the P2P | 309 | implements a protocol for (securely) estimating the current size of the |
297 | network. | 310 | P2P network. |
298 | @item dht/ The distributed hash table (DHT) service provides a | 311 | @item dht/ The distributed hash table (DHT) service provides a |
299 | distributed implementation of a hash table to store blocks under hash keys in | 312 | distributed implementation of a hash table to store blocks under hash |
300 | the P2P network. | 313 | keys in the P2P network. |
301 | @item hostlist/ The hostlist service allows learning about | 314 | @item hostlist/ The hostlist service allows learning about |
302 | other peers in the network by downloading HELLO messages from an HTTP server, | 315 | other peers in the network by downloading HELLO messages from an HTTP |
303 | can be configured to run such an HTTP server and also implements a P2P protocol | 316 | server, can be configured to run such an HTTP server and also implements |
304 | to advertise and automatically learn about other peers that offer a public | 317 | a P2P protocol to advertise and automatically learn about other peers |
305 | hostlist server. | 318 | that offer a public hostlist server. |
306 | @item topology/ The topology service is responsible for | 319 | @item topology/ The topology service is responsible for |
307 | maintaining the mesh topology. It tries to maintain connections to friends | 320 | maintaining the mesh topology. It tries to maintain connections to friends |
308 | (depending on the configuration) and also tries to ensure that the peer has a | 321 | (depending on the configuration) and also tries to ensure that the peer |
309 | decent number of active connections at all times. If necessary, new connections | 322 | has a decent number of active connections at all times. If necessary, new |
310 | are added. All peers should run the topology service, otherwise they may end up | 323 | connections are added. All peers should run the topology service, |
311 | not being connected to any other peer (unless some other service ensures that | 324 | otherwise they may end up not being connected to any other peer (unless |
312 | core establishes the required connections). The topology service also tells the | 325 | some other service ensures that core establishes the required |
313 | transport service which connections are permitted (for friend-to-friend | 326 | connections). The topology service also tells the transport service which |
314 | networking) | 327 | connections are permitted (for friend-to-friend networking) |
315 | @item fs/ The file-sharing (FS) service implements GNUnet's | 328 | @item fs/ The file-sharing (FS) service implements GNUnet's |
316 | file-sharing application. Both anonymous file-sharing (using gap) and | 329 | file-sharing application. Both anonymous file-sharing (using gap) and |
317 | non-anonymous file-sharing (using dht) are supported. | 330 | non-anonymous file-sharing (using dht) are supported. |
318 | @item cadet/ The CADET | 331 | @item cadet/ The CADET |
319 | service provides a general-purpose routing abstraction to create end-to-end | 332 | service provides a general-purpose routing abstraction to create |
320 | encrypted tunnels in mesh networks. We wrote a paper documenting key aspects of | 333 | end-to-end encrypted tunnels in mesh networks. We wrote a paper |
321 | the design. | 334 | documenting key aspects of the design. |
322 | @item tun/ --- libgnunettun Library for building IPv4, IPv6 | 335 | @item tun/ --- libgnunettun Library for building IPv4, IPv6 |
323 | packets and creating checksums for UDP, TCP and ICMP packets. The header | 336 | packets and creating checksums for UDP, TCP and ICMP packets. The header |
324 | defines C structs for common Internet packet formats and in particular structs | 337 | defines C structs for common Internet packet formats and in particular |
325 | for interacting with TUN (virtual network) interfaces. | 338 | structs for interacting with TUN (virtual network) interfaces. |
326 | @item mysql/ --- | 339 | @item mysql/ --- |
327 | libgnunetmysql Library for creating and executing prepared MySQL statements and | 340 | libgnunetmysql Library for creating and executing prepared MySQL |
328 | to manage the connection to the MySQL database. Essentially a lightweight | 341 | statements and to manage the connection to the MySQL database. |
329 | wrapper for the interaction between GNUnet components and libmysqlclient. | 342 | Essentially a lightweight wrapper for the interaction between GNUnet |
330 | @item dns/ Service that allows intercepting and modifying DNS requests of the | 343 | components and libmysqlclient. |
331 | local machine. Currently used for IPv4-IPv6 protocol translation (DNS-ALG) as | 344 | @item dns/ Service that allows intercepting and modifying DNS requests of |
332 | implemented by "pt/" and for the GNUnet naming system. The service can also be | 345 | the local machine. Currently used for IPv4-IPv6 protocol translation |
333 | configured to offer an exit service for DNS traffic. | 346 | (DNS-ALG) as implemented by "pt/" and for the GNUnet naming system. The |
347 | service can also be configured to offer an exit service for DNS traffic. | ||
334 | @item vpn/ The virtual | 348 | @item vpn/ The virtual |
335 | public network (VPN) service provides a virtual tunnel interface (VTUN) for IP | 349 | public network (VPN) service provides a virtual tunnel interface (VTUN) |
336 | routing over GNUnet. Needs some other peers to run an "exit" service to work. | 350 | for IP routing over GNUnet. Needs some other peers to run an "exit" |
337 | Can be activated using the "gnunet-vpn" tool or integrated with DNS using the | 351 | service to work. |
338 | "pt" daemon. | 352 | Can be activated using the "gnunet-vpn" tool or integrated with DNS using |
353 | the "pt" daemon. | ||
339 | @item exit/ Daemon to allow traffic from the VPN to exit this | 354 | @item exit/ Daemon to allow traffic from the VPN to exit this |
340 | peer to the Internet or to specific IP-based services of the local peer. | 355 | peer to the Internet or to specific IP-based services of the local peer. |
341 | Currently, an exit service can only be restricted to IPv4 or IPv6, not to | 356 | Currently, an exit service can only be restricted to IPv4 or IPv6, not to |
342 | specific ports and or IP address ranges. If this is not acceptable, additional | 357 | specific ports and or IP address ranges. If this is not acceptable, |
343 | firewall rules must be added manually. exit currently only works for normal | 358 | additional firewall rules must be added manually. exit currently only |
344 | UDP, TCP and ICMP traffic; DNS queries need to leave the system via a DNS | 359 | works for normal UDP, TCP and ICMP traffic; DNS queries need to leave the |
345 | service. | 360 | system via a DNS service. |
346 | @item pt/ protocol translation daemon. This daemon enables 4-to-6, | 361 | @item pt/ protocol translation daemon. This daemon enables 4-to-6, |
347 | 6-to-4, 4-over-6 or 6-over-4 transitions for the local system. It essentially | 362 | 6-to-4, 4-over-6 or 6-over-4 transitions for the local system. It |
348 | uses "DNS" to intercept DNS replies and then maps results to those offered by | 363 | essentially uses "DNS" to intercept DNS replies and then maps results to |
349 | the VPN, which then sends them using mesh to some daemon offering an | 364 | those offered by the VPN, which then sends them using mesh to some daemon |
350 | appropriate exit service. | 365 | offering an appropriate exit service. |
351 | @item identity/ Management of egos (alter egos) of a | 366 | @item identity/ Management of egos (alter egos) of a user; identities are |
352 | user; identities are essentially named ECC private keys and used for zones in | 367 | essentially named ECC private keys and used for zones in the GNU name |
353 | the GNU name system and for namespaces in file-sharing, but might find other | 368 | system and for namespaces in file-sharing, but might find other uses later |
354 | uses later | ||
355 | @item revocation/ Key revocation service, can be used to revoke the | 369 | @item revocation/ Key revocation service, can be used to revoke the |
356 | private key of an identity if it has been compromised | 370 | private key of an identity if it has been compromised |
357 | @item namecache/ Cache | 371 | @item namecache/ Cache |
358 | for resolution results for the GNU name system; data is encrypted and can be | 372 | for resolution results for the GNU name system; data is encrypted and can |
359 | shared among users, loss of the data should ideally only result in a | 373 | be shared among users, loss of the data should ideally only result in a |
360 | performance degradation (persistence not required) | 374 | performance degradation (persistence not required) |
361 | @item namestore/ Database | 375 | @item namestore/ Database |
362 | for the GNU name system with per-user private information, persistence required | 376 | for the GNU name system with per-user private information, persistence |
377 | required | ||
363 | @item gns/ GNU name system, a GNU approach to DNS and PKI. | 378 | @item gns/ GNU name system, a GNU approach to DNS and PKI. |
364 | @item dv/ A plugin | 379 | @item dv/ A plugin |
365 | for distance-vector (DV)-based routing. DV consists of a service and a | 380 | for distance-vector (DV)-based routing. DV consists of a service and a |
366 | transport plugin to provide peers with the illusion of a direct P2P connection | 381 | transport plugin to provide peers with the illusion of a direct P2P |
367 | for connections that use multiple (typically up to 3) hops in the actual | 382 | connection for connections that use multiple (typically up to 3) hops in |
368 | underlay network. | 383 | the actual underlay network. |
369 | @item regex/ Service for the (distributed) evaluation of | 384 | @item regex/ Service for the (distributed) evaluation of |
370 | regular expressions. | 385 | regular expressions. |
371 | @item scalarproduct/ The scalar product service offers an | 386 | @item scalarproduct/ The scalar product service offers an |
372 | API to perform a secure multiparty computation which calculates a scalar | 387 | API to perform a secure multiparty computation which calculates a scalar |
373 | product between two peers without exposing the private input vectors of the | 388 | product between two peers without exposing the private input vectors of |
374 | peers to each other. | 389 | the peers to each other. |
375 | @item consensus/ The consensus service will allow a set | 390 | @item consensus/ The consensus service will allow a set |
376 | of peers to agree on a set of values via a distributed set union computation. | 391 | of peers to agree on a set of values via a distributed set union |
392 | computation. | ||
377 | @item rest/ The rest API allows access to GNUnet services using RESTful | 393 | @item rest/ The rest API allows access to GNUnet services using RESTful |
378 | interaction. The services provide plugins that can exposed by the rest server. | 394 | interaction. The services provide plugins that can exposed by the rest |
395 | server. | ||
379 | @item experimentation/ The experimentation daemon coordinates distributed | 396 | @item experimentation/ The experimentation daemon coordinates distributed |
380 | experimentation to evaluate transport and ats properties | 397 | experimentation to evaluate transport and ats properties |
381 | @end table | 398 | @end table |
382 | 399 | ||
383 | @c *************************************************************************** | 400 | @c *********************************************************************** |
384 | @node System Architecture | 401 | @node System Architecture |
385 | @section System Architecture | 402 | @section System Architecture |
386 | 403 | ||
387 | GNUnet developers like legos. The blocks are indestructible, can be stacked | 404 | GNUnet developers like legos. The blocks are indestructible, can be |
388 | together to construct complex buildings and it is generally easy to swap one | 405 | stacked together to construct complex buildings and it is generally easy |
389 | block for a different one that has the same shape. GNUnet's architecture is | 406 | to swap one block for a different one that has the same shape. GNUnet's |
390 | based on legos: | 407 | architecture is based on legos: |
391 | 408 | ||
409 | @c images here | ||
392 | 410 | ||
393 | 411 | This chapter documents the GNUnet lego system, also known as GNUnet's | |
394 | This chapter documents the GNUnet lego system, also known as GNUnet's system | 412 | system architecture. |
395 | architecture. | ||
396 | 413 | ||
397 | The most common GNUnet component is a service. Services offer an API (or | 414 | The most common GNUnet component is a service. Services offer an API (or |
398 | several, depending on what you count as "an API") which is implemented as a | 415 | several, depending on what you count as "an API") which is implemented as |
399 | library. The library communicates with the main process of the service using a | 416 | a library. The library communicates with the main process of the service |
400 | service-specific network protocol. The main process of the service typically | 417 | using a service-specific network protocol. The main process of the service |
401 | doesn't fully provide everything that is needed --- it has holes to be filled | 418 | typically doesn't fully provide everything that is needed --- it has holes |
402 | by APIs to other services. | 419 | to be filled by APIs to other services. |
403 | 420 | ||
404 | A special kind of component in GNUnet are user interfaces and daemons. Like | 421 | A special kind of component in GNUnet are user interfaces and daemons. |
405 | services, they have holes to be filled by APIs of other services. Unlike | 422 | Like services, they have holes to be filled by APIs of other services. |
406 | services, daemons do not implement their own network protocol and they have no | 423 | Unlike services, daemons do not implement their own network protocol and |
407 | API: | 424 | they have no API: |
408 | 425 | ||
409 | The GNUnet system provides a range of services, daemons and user interfaces, | 426 | The GNUnet system provides a range of services, daemons and user |
410 | which are then combined into a layered GNUnet instance (also known as a peer). | 427 | interfaces, which are then combined into a layered GNUnet instance (also |
428 | known as a peer). | ||
411 | 429 | ||
412 | Note that while it is generally possible to swap one service for another | 430 | Note that while it is generally possible to swap one service for another |
413 | compatible service, there is often only one implementation. However, during | 431 | compatible service, there is often only one implementation. However, |
414 | development we often have a "new" version of a service in parallel with an | 432 | during development we often have a "new" version of a service in parallel |
415 | "old" version. While the "new" version is not working, developers working on | 433 | with an "old" version. While the "new" version is not working, developers |
416 | other parts of the service can continue their development by simply using the | 434 | working on other parts of the service can continue their development by |
417 | "old" service. Alternative design ideas can also be easily investigated by | 435 | simply using the "old" service. Alternative design ideas can also be |
418 | swapping out individual components. This is typically achieved by simply | 436 | easily investigated by swapping out individual components. This is |
419 | changing the name of the "BINARY" in the respective configuration section. | 437 | typically achieved by simply changing the name of the "BINARY" in the |
420 | 438 | respective configuration section. | |
421 | Key properties of GNUnet services are that they must be separate processes and | 439 | |
422 | that they must protect themselves by applying tight error checking against the | 440 | Key properties of GNUnet services are that they must be separate |
423 | network protocol they implement (thereby achieving a certain degree of | 441 | processes and that they must protect themselves by applying tight error |
424 | robustness). | 442 | checking against the network protocol they implement (thereby achieving a |
443 | certain degree of robustness). | ||
425 | 444 | ||
426 | On the other hand, the APIs are implemented to tolerate failures of the | 445 | On the other hand, the APIs are implemented to tolerate failures of the |
427 | service, isolating their host process from errors by the service. If the | 446 | service, isolating their host process from errors by the service. If the |
428 | service process crashes, other services and daemons around it should not also | 447 | service process crashes, other services and daemons around it should not |
429 | fail, but instead wait for the service process to be restarted by ARM. | 448 | also fail, but instead wait for the service process to be restarted by |
449 | ARM. | ||
430 | 450 | ||
431 | 451 | ||
432 | @c *************************************************************************** | 452 | @c *********************************************************************** |
433 | @node Subsystem stability | 453 | @node Subsystem stability |
434 | @section Subsystem stability | 454 | @section Subsystem stability |
435 | 455 | ||
436 | This page documents the current stability of the various GNUnet subsystems. | 456 | This page documents the current stability of the various GNUnet |
437 | Stability here describes the expected degree of compatibility with future | 457 | subsystems. Stability here describes the expected degree of compatibility |
438 | versions of GNUnet. For each subsystem we distinguish between compatibility on | 458 | with future versions of GNUnet. For each subsystem we distinguish between |
439 | the P2P network level (communication protocol between peers), the IPC level | 459 | compatibility on the P2P network level (communication protocol between |
440 | (communication between the service and the service library) and the API level | 460 | peers), the IPC level (communication between the service and the service |
441 | (stability of the API). P2P compatibility is relevant in terms of which | 461 | library) and the API level (stability of the API). P2P compatibility is |
442 | applications are likely going to be able to communicate with future versions of | 462 | relevant in terms of which applications are likely going to be able to |
443 | the network. IPC communication is relevant for the implementation of language | 463 | communicate with future versions of the network. IPC communication is |
444 | bindings that re-implement the IPC messages. Finally, API compatibility is | 464 | relevant for the implementation of language bindings that re-implement the |
445 | relevant to developers that hope to be able to avoid changes to applications | 465 | IPC messages. Finally, API compatibility is relevant to developers that |
446 | build on top of the APIs of the framework. | 466 | hope to be able to avoid changes to applications build on top of the APIs |
467 | of the framework. | ||
447 | 468 | ||
448 | The following table summarizes our current view of the stability of the | 469 | The following table summarizes our current view of the stability of the |
449 | respective protocols or APIs: | 470 | respective protocols or APIs: |
@@ -495,20 +516,21 @@ Here is a rough explanation of the values: | |||
495 | @item stable | 516 | @item stable |
496 | No incompatible changes are planned at this time; for IPC/APIs, if | 517 | No incompatible changes are planned at this time; for IPC/APIs, if |
497 | there are incompatible changes, they will be minor and might only require | 518 | there are incompatible changes, they will be minor and might only require |
498 | minimal changes to existing code; for P2P, changes will be avoided if at all | 519 | minimal changes to existing code; for P2P, changes will be avoided if at |
499 | possible for the 0.10.x-series | 520 | all possible for the 0.10.x-series |
500 | 521 | ||
501 | @item testing | 522 | @item testing |
502 | No incompatible changes are | 523 | No incompatible changes are |
503 | planned at this time, but the code is still known to be in flux; so while we | 524 | planned at this time, but the code is still known to be in flux; so while |
504 | have no concrete plans, our expectation is that there will still be minor | 525 | we have no concrete plans, our expectation is that there will still be |
505 | modifications; for P2P, changes will likely be extensions that should not break | 526 | minor modifications; for P2P, changes will likely be extensions that |
506 | existing code | 527 | should not break existing code |
507 | 528 | ||
508 | @item unstable | 529 | @item unstable |
509 | Changes are planned and will happen; however, they | 530 | Changes are planned and will happen; however, they |
510 | will not be totally radical and the result should still resemble what is there | 531 | will not be totally radical and the result should still resemble what is |
511 | now; nevertheless, anticipated changes will break protocol/API compatibility | 532 | there now; nevertheless, anticipated changes will break protocol/API |
533 | compatibility | ||
512 | 534 | ||
513 | @item experimental | 535 | @item experimental |
514 | Changes are planned and the result may look nothing like | 536 | Changes are planned and the result may look nothing like |
@@ -521,7 +543,7 @@ Someone should think about where this subsystem headed | |||
521 | This subsystem does not have an API/IPC-protocol/P2P-protocol | 543 | This subsystem does not have an API/IPC-protocol/P2P-protocol |
522 | @end table | 544 | @end table |
523 | 545 | ||
524 | @c *************************************************************************** | 546 | @c *********************************************************************** |
525 | @node Naming conventions and coding style guide | 547 | @node Naming conventions and coding style guide |
526 | @section Naming conventions and coding style guide | 548 | @section Naming conventions and coding style guide |
527 | 549 | ||
@@ -529,7 +551,7 @@ Here you can find some rules to help you write code for GNUnet. | |||
529 | 551 | ||
530 | 552 | ||
531 | 553 | ||
532 | @c *************************************************************************** | 554 | @c *********************************************************************** |
533 | @menu | 555 | @menu |
534 | * Naming conventions:: | 556 | * Naming conventions:: |
535 | * Coding style:: | 557 | * Coding style:: |
@@ -539,7 +561,7 @@ Here you can find some rules to help you write code for GNUnet. | |||
539 | @subsection Naming conventions | 561 | @subsection Naming conventions |
540 | 562 | ||
541 | 563 | ||
542 | @c *************************************************************************** | 564 | @c *********************************************************************** |
543 | @menu | 565 | @menu |
544 | * include files:: | 566 | * include files:: |
545 | * binaries:: | 567 | * binaries:: |
@@ -571,7 +593,7 @@ Here you can find some rules to help you write code for GNUnet. | |||
571 | @end itemize | 593 | @end itemize |
572 | @end itemize | 594 | @end itemize |
573 | 595 | ||
574 | @c *************************************************************************** | 596 | @c *********************************************************************** |
575 | @node binaries | 597 | @node binaries |
576 | @subsubsection binaries | 598 | @subsubsection binaries |
577 | 599 | ||
@@ -584,20 +606,20 @@ Here you can find some rules to help you write code for GNUnet. | |||
584 | @item libgnunetxxx.so: library for API xxx | 606 | @item libgnunetxxx.so: library for API xxx |
585 | @end itemize | 607 | @end itemize |
586 | 608 | ||
587 | @c *************************************************************************** | 609 | @c *********************************************************************** |
588 | @node logging | 610 | @node logging |
589 | @subsubsection logging | 611 | @subsubsection logging |
590 | 612 | ||
591 | @itemize @bullet | 613 | @itemize @bullet |
592 | @item services and daemons use their directory name in GNUNET_log_setup (i.e. | 614 | @item services and daemons use their directory name in GNUNET_log_setup |
593 | 'core') and log using plain 'GNUNET_log'. | 615 | (i.e. 'core') and log using plain 'GNUNET_log'. |
594 | @item command-line tools use their full name in GNUNET_log_setup (i.e. | 616 | @item command-line tools use their full name in GNUNET_log_setup (i.e. |
595 | 'gnunet-publish') and log using plain 'GNUNET_log'. | 617 | 'gnunet-publish') and log using plain 'GNUNET_log'. |
596 | @item service access libraries log using 'GNUNET_log_from' and use | 618 | @item service access libraries log using 'GNUNET_log_from' and use |
597 | 'DIRNAME-api' for the component (i.e. 'core-api') | 619 | 'DIRNAME-api' for the component (i.e. 'core-api') |
598 | @item pure libraries (without associated service) use 'GNUNET_log_from' with | 620 | @item pure libraries (without associated service) use 'GNUNET_log_from' |
599 | the component set to their library name (without lib or '.so'), which should | 621 | with the component set to their library name (without lib or '.so'), |
600 | also be their directory name (i.e. 'nat') | 622 | which should also be their directory name (i.e. 'nat') |
601 | @item plugins should use 'GNUNET_log_from' with the directory name and the | 623 | @item plugins should use 'GNUNET_log_from' with the directory name and the |
602 | plugin name combined to produce the component name (i.e. 'transport-tcp'). | 624 | plugin name combined to produce the component name (i.e. 'transport-tcp'). |
603 | @item logging should be unified per-file by defining a LOG macro with the | 625 | @item logging should be unified per-file by defining a LOG macro with the |
@@ -605,36 +627,38 @@ appropriate arguments, along these lines:@ #define LOG(kind,...) | |||
605 | GNUNET_log_from (kind, "example-api",__VA_ARGS__) | 627 | GNUNET_log_from (kind, "example-api",__VA_ARGS__) |
606 | @end itemize | 628 | @end itemize |
607 | 629 | ||
608 | @c *************************************************************************** | 630 | @c *********************************************************************** |
609 | @node configuration | 631 | @node configuration |
610 | @subsubsection configuration | 632 | @subsubsection configuration |
611 | 633 | ||
612 | @itemize @bullet | 634 | @itemize @bullet |
613 | @item paths (that are substituted in all filenames) are in PATHS (have as few | 635 | @item paths (that are substituted in all filenames) are in PATHS (have as |
614 | as possible) | 636 | few as possible) |
615 | @item all options for a particular module (src/MODULE) are under [MODULE] | 637 | @item all options for a particular module (src/MODULE) are under [MODULE] |
616 | @item options for a plugin of a module are under [MODULE-PLUGINNAME] | 638 | @item options for a plugin of a module are under [MODULE-PLUGINNAME] |
617 | @end itemize | 639 | @end itemize |
618 | 640 | ||
619 | @c *************************************************************************** | 641 | @c *********************************************************************** |
620 | @node exported symbols | 642 | @node exported symbols |
621 | @subsubsection exported symbols | 643 | @subsubsection exported symbols |
622 | 644 | ||
623 | @itemize @bullet | 645 | @itemize @bullet |
624 | @item must start with "GNUNET_modulename_" and be defined in "modulename.c" | 646 | @item must start with "GNUNET_modulename_" and be defined in |
647 | "modulename.c" | ||
625 | @item exceptions: those defined in gnunet_common.h | 648 | @item exceptions: those defined in gnunet_common.h |
626 | @end itemize | 649 | @end itemize |
627 | 650 | ||
628 | @c *************************************************************************** | 651 | @c *********************************************************************** |
629 | @node private (library-internal) symbols (including structs and macros) | 652 | @node private (library-internal) symbols (including structs and macros) |
630 | @subsubsection private (library-internal) symbols (including structs and macros) | 653 | @subsubsection private (library-internal) symbols (including structs and macros) |
631 | 654 | ||
632 | @itemize @bullet | 655 | @itemize @bullet |
633 | @item must NOT start with any prefix | 656 | @item must NOT start with any prefix |
634 | @item must not be exported in a way that linkers could use them or@ other | 657 | @item must not be exported in a way that linkers could use them or@ other |
635 | libraries might see them via headers; they must be either@ declared/defined in | 658 | libraries might see them via headers; they must be either@ |
636 | C source files or in headers that are in@ the respective directory under | 659 | declared/defined in C source files or in headers that are in@ the |
637 | src/modulename/ and NEVER be@ declared in src/include/. | 660 | respective directory under src/modulename/ and NEVER be@ declared |
661 | in src/include/. | ||
638 | @end itemize | 662 | @end itemize |
639 | 663 | ||
640 | @node testcases | 664 | @node testcases |
@@ -645,17 +669,18 @@ src/modulename/ and NEVER be@ declared in src/include/. | |||
645 | @item "case-description" maybe omitted if there is only one test | 669 | @item "case-description" maybe omitted if there is only one test |
646 | @end itemize | 670 | @end itemize |
647 | 671 | ||
648 | @c *************************************************************************** | 672 | @c *********************************************************************** |
649 | @node performance tests | 673 | @node performance tests |
650 | @subsubsection performance tests | 674 | @subsubsection performance tests |
651 | 675 | ||
652 | @itemize @bullet | 676 | @itemize @bullet |
653 | @item must be called "perf_module-under-test_case-description.c" | 677 | @item must be called "perf_module-under-test_case-description.c" |
654 | @item "case-description" maybe omitted if there is only one performance test | 678 | @item "case-description" maybe omitted if there is only one performance |
679 | test | ||
655 | @item Must only be run if HAVE_BENCHMARKS is satisfied | 680 | @item Must only be run if HAVE_BENCHMARKS is satisfied |
656 | @end itemize | 681 | @end itemize |
657 | 682 | ||
658 | @c *************************************************************************** | 683 | @c *********************************************************************** |
659 | @node src/ directories | 684 | @node src/ directories |
660 | @subsubsection src/ directories | 685 | @subsubsection src/ directories |
661 | 686 | ||
@@ -663,15 +688,15 @@ src/modulename/ and NEVER be@ declared in src/include/. | |||
663 | @item gnunet-NAME: end-user applications (i.e., gnunet-search, gnunet-arm) | 688 | @item gnunet-NAME: end-user applications (i.e., gnunet-search, gnunet-arm) |
664 | @item gnunet-service-NAME: service processes with accessor library (i.e., | 689 | @item gnunet-service-NAME: service processes with accessor library (i.e., |
665 | gnunet-service-arm) | 690 | gnunet-service-arm) |
666 | @item libgnunetNAME: accessor library (_service.h-header) or standalone library | 691 | @item libgnunetNAME: accessor library (_service.h-header) or standalone |
667 | (_lib.h-header) | 692 | library (_lib.h-header) |
668 | @item gnunet-daemon-NAME: daemon process without accessor library (i.e., | 693 | @item gnunet-daemon-NAME: daemon process without accessor library (i.e., |
669 | gnunet-daemon-hostlist) and no GNUnet management port | 694 | gnunet-daemon-hostlist) and no GNUnet management port |
670 | @item libgnunet_plugin_DIR_NAME: loadable plugins (i.e., | 695 | @item libgnunet_plugin_DIR_NAME: loadable plugins (i.e., |
671 | libgnunet_plugin_transport_tcp) | 696 | libgnunet_plugin_transport_tcp) |
672 | @end itemize | 697 | @end itemize |
673 | 698 | ||
674 | @c *************************************************************************** | 699 | @c *********************************************************************** |
675 | @node Coding style | 700 | @node Coding style |
676 | @subsection Coding style | 701 | @subsection Coding style |
677 | 702 | ||
@@ -691,18 +716,18 @@ instead of | |||
691 | int i,j; | 716 | int i,j; |
692 | @end example | 717 | @end example |
693 | 718 | ||
694 | This helps keep diffs small and forces developers to think precisely about the | 719 | This helps keep diffs small and forces developers to think precisely about |
695 | type of every variable. Note that @code{char *} is different from @code{const | 720 | the type of every variable. Note that @code{char *} is different from |
696 | char*} and @code{int} is different from @code{unsigned int} or @code{uint32_t}. | 721 | @code{const char*} and @code{int} is different from @code{unsigned int} |
697 | Each variable type should be chosen with care. | 722 | or @code{uint32_t}. Each variable type should be chosen with care. |
698 | 723 | ||
699 | @item While @code{goto} should generally be avoided, having a @code{goto} to | 724 | @item While @code{goto} should generally be avoided, having a @code{goto} |
700 | the end of a function to a block of clean up statements (free, close, etc.) can | 725 | to the end of a function to a block of clean up statements (free, close, |
701 | be acceptable. | 726 | etc.) can be acceptable. |
702 | 727 | ||
703 | @item Conditions should be written with constants on the left (to avoid | 728 | @item Conditions should be written with constants on the left (to avoid |
704 | accidental assignment) and with the 'true' target being either the 'error' case | 729 | accidental assignment) and with the 'true' target being either the |
705 | or the significantly simpler continuation. For example:@ | 730 | 'error' case or the significantly simpler continuation. For example: |
706 | 731 | ||
707 | @example | 732 | @example |
708 | if (0 != stat ("filename," &sbuf)) @{ error(); @} else @{ | 733 | if (0 != stat ("filename," &sbuf)) @{ error(); @} else @{ |
@@ -710,38 +735,38 @@ if (0 != stat ("filename," &sbuf)) @{ error(); @} else @{ | |||
710 | @} | 735 | @} |
711 | @end example | 736 | @end example |
712 | 737 | ||
713 | |||
714 | instead of | 738 | instead of |
739 | |||
715 | @example | 740 | @example |
716 | if (stat ("filename," &sbuf) == 0) @{ | 741 | if (stat ("filename," &sbuf) == 0) @{ |
717 | /* handle normal case here */ | 742 | /* handle normal case here */ |
718 | @} else @{ error(); @} | 743 | @} else @{ error(); @} |
719 | @end example | 744 | @end example |
720 | 745 | ||
746 | If possible, the error clause should be terminated with a 'return' (or | ||
747 | 'goto' to some cleanup routine) and in this case, the 'else' clause | ||
748 | should be omitted: | ||
721 | 749 | ||
722 | If possible, the error clause should be terminated with a 'return' (or 'goto' | ||
723 | to some cleanup routine) and in this case, the 'else' clause should be omitted: | ||
724 | @example | 750 | @example |
725 | if (0 != stat ("filename," &sbuf)) @{ error(); return; @} | 751 | if (0 != stat ("filename," &sbuf)) @{ error(); return; @} |
726 | /* handle normal case here */ | 752 | /* handle normal case here */ |
727 | @end example | 753 | @end example |
728 | 754 | ||
755 | This serves to avoid deep nesting. The 'constants on the left' rule | ||
756 | applies to all constants (including. @code{GNUNET_SCHEDULER_NO_TASK}), | ||
757 | NULL, and enums). With the two above rules (constants on left, errors in | ||
758 | 'true' branch), there is only one way to write most branches correctly. | ||
729 | 759 | ||
730 | This serves to avoid deep nesting. The 'constants on the left' rule applies to | 760 | @item Combined assignments and tests are allowed if they do not hinder |
731 | all constants (including. @code{GNUNET_SCHEDULER_NO_TASK}), NULL, and enums). | 761 | code clarity. For example, one can write: |
732 | With the two above rules (constants on left, errors in 'true' branch), there is | ||
733 | only one way to write most branches correctly. | ||
734 | |||
735 | @item Combined assignments and tests are allowed if they do not hinder code | ||
736 | clarity. For example, one can write:@ | ||
737 | 762 | ||
738 | @example | 763 | @example |
739 | if (NULL == (value = lookup_function())) @{ error(); return; @} | 764 | if (NULL == (value = lookup_function())) @{ error(); return; @} |
740 | @end example | 765 | @end example |
741 | 766 | ||
742 | 767 | ||
743 | @item Use @code{break} and @code{continue} wherever possible to avoid deep(er) | 768 | @item Use @code{break} and @code{continue} wherever possible to avoid |
744 | nesting. Thus, we would write:@ | 769 | deep(er) nesting. Thus, we would write: |
745 | 770 | ||
746 | @example | 771 | @example |
747 | next = head; while (NULL != (pos = next)) @{ next = pos->next; if (! | 772 | next = head; while (NULL != (pos = next)) @{ next = pos->next; if (! |
@@ -759,9 +784,9 @@ pos->next; if (should_free (pos)) @{ | |||
759 | @end example | 784 | @end example |
760 | 785 | ||
761 | 786 | ||
762 | @item We primarily use @code{for} and @code{while} loops. A @code{while} loop | 787 | @item We primarily use @code{for} and @code{while} loops. A @code{while} |
763 | is used if the method for advancing in the loop is not a straightforward | 788 | loop is used if the method for advancing in the loop is not a |
764 | increment operation. In particular, we use:@ | 789 | straightforward increment operation. In particular, we use: |
765 | 790 | ||
766 | @example | 791 | @example |
767 | next = head; | 792 | next = head; |
@@ -776,11 +801,12 @@ while (NULL != (pos = next)) | |||
776 | @end example | 801 | @end example |
777 | 802 | ||
778 | 803 | ||
779 | to free entries in a list (as the iteration changes the structure of the list | 804 | to free entries in a list (as the iteration changes the structure of the |
780 | due to the free; the equivalent @code{for} loop does no longer follow the | 805 | list due to the free; the equivalent @code{for} loop does no longer |
781 | simple @code{for} paradigm of @code{for(INIT;TEST;INC)}). However, for loops | 806 | follow the simple @code{for} paradigm of @code{for(INIT;TEST;INC)}). |
782 | that do follow the simple @code{for} paradigm we do use @code{for}, even if it | 807 | However, for loops that do follow the simple @code{for} paradigm we do |
783 | involves linked lists: | 808 | use @code{for}, even if it involves linked lists: |
809 | |||
784 | @example | 810 | @example |
785 | /* simple iteration over a linked list */ | 811 | /* simple iteration over a linked list */ |
786 | for (pos = head; NULL != pos; pos = pos->next) | 812 | for (pos = head; NULL != pos; pos = pos->next) |
@@ -791,11 +817,13 @@ for (pos = head; NULL != pos; pos = pos->next) | |||
791 | 817 | ||
792 | 818 | ||
793 | @item The first argument to all higher-order functions in GNUnet must be | 819 | @item The first argument to all higher-order functions in GNUnet must be |
794 | declared to be of type @code{void *} and is reserved for a closure. We do not | 820 | declared to be of type @code{void *} and is reserved for a closure. We do |
795 | use inner functions, as trampolines would conflict with setups that use | 821 | not use inner functions, as trampolines would conflict with setups that |
796 | non-executable stacks.@ The first statement in a higher-order function, which | 822 | use non-executable stacks.@ The first statement in a higher-order |
797 | unusually should be part of the variable declarations, should assign the | 823 | function, which unusually should be part of the variable declarations, |
798 | @code{cls} argument to the precise expected type. For example: | 824 | should assign the @code{cls} argument to the precise expected type. |
825 | For example: | ||
826 | |||
799 | @example | 827 | @example |
800 | int callback (void *cls, char *args) @{ | 828 | int callback (void *cls, char *args) @{ |
801 | struct Foo *foo = cls; int other_variables; | 829 | struct Foo *foo = cls; int other_variables; |
@@ -805,9 +833,9 @@ int callback (void *cls, char *args) @{ | |||
805 | @end example | 833 | @end example |
806 | 834 | ||
807 | 835 | ||
808 | @item It is good practice to write complex @code{if} expressions instead of | 836 | @item It is good practice to write complex @code{if} expressions instead |
809 | using deeply nested @code{if} statements. However, except for addition and | 837 | of using deeply nested @code{if} statements. However, except for addition |
810 | multiplication, all operators should use parens. This is fine:@ | 838 | and multiplication, all operators should use parens. This is fine: |
811 | 839 | ||
812 | @example | 840 | @example |
813 | if ( (1 == foo) || ((0 == bar) && (x != y)) ) | 841 | if ( (1 == foo) || ((0 == bar) && (x != y)) ) |
@@ -825,42 +853,44 @@ if (0 == bar && x != y) | |||
825 | 853 | ||
826 | 854 | ||
827 | Note that splitting the @code{if} statement above is debateable as the | 855 | Note that splitting the @code{if} statement above is debateable as the |
828 | @code{return x} is a very trivial statement. However, once the logic after the | 856 | @code{return x} is a very trivial statement. However, once the logic after |
829 | branch becomes more complicated (and is still identical), the "or" formulation | 857 | the branch becomes more complicated (and is still identical), the "or" |
830 | should be used for sure. | 858 | formulation should be used for sure. |
831 | 859 | ||
832 | @item There should be two empty lines between the end of the function and the | 860 | @item There should be two empty lines between the end of the function and |
833 | comments describing the following function. There should be a single empty line | 861 | the comments describing the following function. There should be a single |
834 | after the initial variable declarations of a function. If a function has no | 862 | empty line after the initial variable declarations of a function. If a |
835 | local variables, there should be no initial empty line. If a long function | 863 | function has no local variables, there should be no initial empty line. If |
836 | consists of several complex steps, those steps might be separated by an empty | 864 | a long function consists of several complex steps, those steps might be |
837 | line (possibly followed by a comment describing the following step). The code | 865 | separated by an empty line (possibly followed by a comment describing the |
838 | should not contain empty lines in arbitrary places; if in doubt, it is likely | 866 | following step). The code should not contain empty lines in arbitrary |
839 | better to NOT have an empty line (this way, more code will fit on the screen). | 867 | places; if in doubt, it is likely better to NOT have an empty line (this |
868 | way, more code will fit on the screen). | ||
840 | @end itemize | 869 | @end itemize |
841 | 870 | ||
842 | @c *************************************************************************** | 871 | @c *********************************************************************** |
843 | @node Build-system | 872 | @node Build-system |
844 | @section Build-system | 873 | @section Build-system |
845 | 874 | ||
846 | If you have code that is likely not to compile or build rules you might want to | 875 | If you have code that is likely not to compile or build rules you might |
847 | not trigger for most developers, use "if HAVE_EXPERIMENTAL" in your | 876 | want to not trigger for most developers, use "if HAVE_EXPERIMENTAL" in |
848 | Makefile.am. Then it is OK to (temporarily) add non-compiling (or | 877 | your Makefile.am. Then it is OK to (temporarily) add non-compiling (or |
849 | known-to-not-port) code. | 878 | known-to-not-port) code. |
850 | 879 | ||
851 | If you want to compile all testcases but NOT run them, run configure with the@ | 880 | If you want to compile all testcases but NOT run them, run configure with |
852 | @code{--enable-test-suppression} option. | 881 | the @code{--enable-test-suppression} option. |
853 | 882 | ||
854 | If you want to run all testcases, including those that take a while, run | 883 | If you want to run all testcases, including those that take a while, run |
855 | configure with the@ @code{--enable-expensive-testcases} option. | 884 | configure with the @code{--enable-expensive-testcases} option. |
856 | 885 | ||
857 | If you want to compile and run benchmarks, run configure with the@ | 886 | If you want to compile and run benchmarks, run configure with the |
858 | @code{--enable-benchmarks} option. | 887 | @code{--enable-benchmarks} option. |
859 | 888 | ||
860 | If you want to obtain code coverage results, run configure with the@ | 889 | If you want to obtain code coverage results, run configure with the |
861 | @code{--enable-coverage} option and run the coverage.sh script in contrib/. | 890 | @code{--enable-coverage} option and run the coverage.sh script in |
891 | @file{contrib/}. | ||
862 | 892 | ||
863 | @c *************************************************************************** | 893 | @c *********************************************************************** |
864 | @node Developing extensions for GNUnet using the gnunet-ext template | 894 | @node Developing extensions for GNUnet using the gnunet-ext template |
865 | @section Developing extensions for GNUnet using the gnunet-ext template | 895 | @section Developing extensions for GNUnet using the gnunet-ext template |
866 | 896 | ||
@@ -876,37 +906,44 @@ First of all you have to obtain gnunet-ext from git: | |||
876 | @code{git clone https://gnunet.org/git/gnunet-ext.git} | 906 | @code{git clone https://gnunet.org/git/gnunet-ext.git} |
877 | 907 | ||
878 | The next step is to bootstrap and configure it. For configure you have to | 908 | The next step is to bootstrap and configure it. For configure you have to |
879 | provide the path containing GNUnet with @code{--with-gnunet=/path/to/gnunet} | 909 | provide the path containing GNUnet with |
880 | and the prefix where you want the install the extension using | 910 | @code{--with-gnunet=/path/to/gnunet} and the prefix where you want the |
881 | @code{--prefix=/path/to/install}@ @code{@ ./bootstrap@ ./configure | 911 | install the extension using @code{--prefix=/path/to/install}: |
882 | --prefix=/path/to/install --with-gnunet=/path/to/gnunet@ } | 912 | |
913 | @example | ||
914 | ./bootstrap | ||
915 | ./configure --prefix=/path/to/install --with-gnunet=/path/to/gnunet | ||
916 | @end example | ||
883 | 917 | ||
884 | When your GNUnet installation is not included in the default linker search | 918 | When your GNUnet installation is not included in the default linker search |
885 | path, you have to add @code{/path/to/gnunet} to the file @code{/etc/ld.so.conf} | 919 | path, you have to add @code{/path/to/gnunet} to the file |
886 | and run @code{ldconfig} or your add it to the environmental variable | 920 | @file{/etc/ld.so.conf} and run @code{ldconfig} or your add it to the |
887 | @code{LD_LIBRARY_PATH} by using | 921 | environmental variable @code{LD_LIBRARY_PATH} by using |
888 | 922 | ||
889 | @code{export LD_LIBRARY_PATH=/path/to/gnunet/lib} | 923 | @code{export LD_LIBRARY_PATH=/path/to/gnunet/lib} |
890 | 924 | ||
891 | @c *************************************************************************** | 925 | @c *********************************************************************** |
892 | @node Writing testcases | 926 | @node Writing testcases |
893 | @section Writing testcases | 927 | @section Writing testcases |
894 | 928 | ||
895 | Ideally, any non-trivial GNUnet code should be covered by automated testcases. | 929 | Ideally, any non-trivial GNUnet code should be covered by automated |
896 | Testcases should reside in the same place as the code that is being tested. The | 930 | testcases. Testcases should reside in the same place as the code that is |
897 | name of source files implementing tests should begin with "test_" followed by | 931 | being tested. The name of source files implementing tests should begin |
898 | the name of the file that contains the code that is being tested. | 932 | with "test_" followed by the name of the file that contains the code that |
899 | 933 | is being tested. | |
900 | Testcases in GNUnet should be integrated with the autotools build system. This | 934 | |
901 | way, developers and anyone building binary packages will be able to run all | 935 | Testcases in GNUnet should be integrated with the autotools build system. |
902 | testcases simply by running @code{make check}. The final testcases shipped with | 936 | This way, developers and anyone building binary packages will be able to |
903 | the distribution should output at most some brief progress information and not | 937 | run all testcases simply by running @code{make check}. The final |
904 | display debug messages by default. The success or failure of a testcase must be | 938 | testcases shipped with the distribution should output at most some brief |
905 | indicated by returning zero (success) or non-zero (failure) from the main | 939 | progress information and not display debug messages by default. The |
906 | method of the testcase. The integration with the autotools is relatively | 940 | success or failure of a testcase must be indicated by returning zero |
907 | straightforward and only requires modifications to the @code{Makefile.am} in | 941 | (success) or non-zero (failure) from the main method of the testcase. The |
908 | the directory containing the testcase. For a testcase testing the code in | 942 | integration with the autotools is relatively straightforward and only |
909 | @code{foo.c} the @code{Makefile.am} would contain the following lines: | 943 | requires modifications to the @code{Makefile.am} in the directory |
944 | containing the testcase. For a testcase testing the code in @code{foo.c} | ||
945 | the @code{Makefile.am} would contain the following lines: | ||
946 | |||
910 | @example | 947 | @example |
911 | check_PROGRAMS = test_foo TESTS = $(check_PROGRAMS) test_foo_SOURCES = | 948 | check_PROGRAMS = test_foo TESTS = $(check_PROGRAMS) test_foo_SOURCES = |
912 | test_foo.c test_foo_LDADD = $(top_builddir)/src/util/libgnunetutil.la | 949 | test_foo.c test_foo_LDADD = $(top_builddir)/src/util/libgnunetutil.la |
@@ -915,51 +952,53 @@ test_foo.c test_foo_LDADD = $(top_builddir)/src/util/libgnunetutil.la | |||
915 | Naturally, other libraries used by the testcase may be specified in the | 952 | Naturally, other libraries used by the testcase may be specified in the |
916 | @code{LDADD} directive as necessary. | 953 | @code{LDADD} directive as necessary. |
917 | 954 | ||
918 | Often testcases depend on additional input files, such as a configuration file. | 955 | Often testcases depend on additional input files, such as a configuration |
919 | These support files have to be listed using the EXTRA_DIST directive in order | 956 | file. These support files have to be listed using the EXTRA_DIST |
920 | to ensure that they are included in the distribution. Example: | 957 | directive in order to ensure that they are included in the distribution. |
958 | Example: | ||
959 | |||
921 | @example | 960 | @example |
922 | EXTRA_DIST = test_foo_data.conf | 961 | EXTRA_DIST = test_foo_data.conf |
923 | @end example | 962 | @end example |
924 | 963 | ||
964 | Executing @code{make check} will run all testcases in the current | ||
965 | directory and all subdirectories. Testcases can be compiled individually | ||
966 | by running @code{make test_foo} and then invoked directly using | ||
967 | @code{./test_foo}. Note that due to the use of plugins in GNUnet, it is | ||
968 | typically necessary to run @code{make install} before running any | ||
969 | testcases. Thus the canonical command @code{make check install} has to be | ||
970 | changed to @code{make install check} for GNUnet. | ||
925 | 971 | ||
926 | Executing @code{make check} will run all testcases in the current directory and | 972 | @c *********************************************************************** |
927 | all subdirectories. Testcases can be compiled individually by running | ||
928 | @code{make test_foo} and then invoked directly using @code{./test_foo}. Note | ||
929 | that due to the use of plugins in GNUnet, it is typically necessary to run | ||
930 | @code{make install} before running any testcases. Thus the canonical command | ||
931 | @code{make check install} has to be changed to @code{make install check} for | ||
932 | GNUnet. | ||
933 | |||
934 | @c *************************************************************************** | ||
935 | @node GNUnet's TESTING library | 973 | @node GNUnet's TESTING library |
936 | @section GNUnet's TESTING library | 974 | @section GNUnet's TESTING library |
937 | 975 | ||
938 | The TESTING library is used for writing testcases which involve starting a | 976 | The TESTING library is used for writing testcases which involve starting a |
939 | single or multiple peers. While peers can also be started by testcases using | 977 | single or multiple peers. While peers can also be started by testcases |
940 | the ARM subsystem, using TESTING library provides an elegant way to do this. | 978 | using the ARM subsystem, using TESTING library provides an elegant way to |
941 | The configurations of the peers are auto-generated from a given template to | 979 | do this. The configurations of the peers are auto-generated from a given |
942 | have non-conflicting port numbers ensuring that peers' services do not run into | 980 | template to have non-conflicting port numbers ensuring that peers' |
943 | bind errors. This is achieved by testing ports' availability by binding a | 981 | services do not run into bind errors. This is achieved by testing ports' |
944 | listening socket to them before allocating them to services in the generated | 982 | availability by binding a listening socket to them before allocating them |
945 | configurations. | 983 | to services in the generated configurations. |
946 | 984 | ||
947 | An another advantage while using TESTING is that it shortens the testcase | 985 | An another advantage while using TESTING is that it shortens the testcase |
948 | startup time as the hostkeys for peers are copied from a pre-computed set of | 986 | startup time as the hostkeys for peers are copied from a pre-computed set |
949 | hostkeys instead of generating them at peer startup which may take a | 987 | of hostkeys instead of generating them at peer startup which may take a |
950 | considerable amount of time when starting multiple peers or on an embedded | 988 | considerable amount of time when starting multiple peers or on an embedded |
951 | processor. | 989 | processor. |
952 | 990 | ||
953 | TESTING also allows for certain services to be shared among peers. This feature | 991 | TESTING also allows for certain services to be shared among peers. This |
954 | is invaluable when testing with multiple peers as it helps to reduce the number | 992 | feature is invaluable when testing with multiple peers as it helps to |
955 | of services run per each peer and hence the total number of processes run per | 993 | reduce the number of services run per each peer and hence the total |
956 | testcase. | 994 | number of processes run per testcase. |
957 | 995 | ||
958 | TESTING library only handles creating, starting and stopping peers. Features | 996 | TESTING library only handles creating, starting and stopping peers. |
959 | useful for testcases such as connecting peers in a topology are not available | 997 | Features useful for testcases such as connecting peers in a topology are |
960 | in TESTING but are available in the TESTBED subsystem. Furthermore, TESTING | 998 | not available in TESTING but are available in the TESTBED subsystem. |
961 | only creates peers on the localhost, however by using TESTBED testcases can | 999 | Furthermore, TESTING only creates peers on the localhost, however by |
962 | benefit from creating peers across multiple hosts. | 1000 | using TESTBED testcases can benefit from creating peers across multiple |
1001 | hosts. | ||
963 | 1002 | ||
964 | @menu | 1003 | @menu |
965 | * API:: | 1004 | * API:: |
@@ -968,113 +1007,118 @@ benefit from creating peers across multiple hosts. | |||
968 | * Testing with multiple processes:: | 1007 | * Testing with multiple processes:: |
969 | @end menu | 1008 | @end menu |
970 | 1009 | ||
971 | @c *************************************************************************** | 1010 | @c *********************************************************************** |
972 | @node API | 1011 | @node API |
973 | @subsection API | 1012 | @subsection API |
974 | 1013 | ||
975 | TESTING abstracts a group of peers as a TESTING system. All peers in a system | 1014 | TESTING abstracts a group of peers as a TESTING system. All peers in a |
976 | have common hostname and no two services of these peers have a same port or a | 1015 | system have common hostname and no two services of these peers have a |
977 | UNIX domain socket path. | 1016 | same port or a UNIX domain socket path. |
978 | 1017 | ||
979 | TESTING system can be created with the function | 1018 | TESTING system can be created with the function |
980 | @code{GNUNET_TESTING_system_create()} which returns a handle to the system. | 1019 | @code{GNUNET_TESTING_system_create()} which returns a handle to the |
981 | This function takes a directory path which is used for generating the | 1020 | system. This function takes a directory path which is used for generating |
982 | configurations of peers, an IP address from which connections to the peers' | 1021 | the configurations of peers, an IP address from which connections to the |
983 | services should be allowed, the hostname to be used in peers' configuration, | 1022 | peers' services should be allowed, the hostname to be used in peers' |
984 | and an array of shared service specifications of type @code{struct | 1023 | configuration, and an array of shared service specifications of type |
985 | GNUNET_TESTING_SharedService}. | 1024 | @code{struct GNUNET_TESTING_SharedService}. |
986 | 1025 | ||
987 | The shared service specification must specify the name of the service to share, | 1026 | The shared service specification must specify the name of the service to |
988 | the configuration pertaining to that shared service and the maximum number of | 1027 | share, the configuration pertaining to that shared service and the |
989 | peers that are allowed to share a single instance of the shared service. | 1028 | maximum number of peers that are allowed to share a single instance of |
990 | 1029 | the shared service. | |
991 | TESTING system created with @code{GNUNET_TESTING_system_create()} chooses ports | 1030 | |
992 | from the default range 12000 - 56000 while auto-generating configurations for | 1031 | TESTING system created with @code{GNUNET_TESTING_system_create()} chooses |
993 | peers. This range can be customised with the function | 1032 | ports from the default range 12000 - 56000 while auto-generating |
994 | @code{GNUNET_TESTING_system_create_with_portrange()}. This function is similar | 1033 | configurations for peers. This range can be customised with the function |
995 | to @code{GNUNET_TESTING_system_create()} except that it take 2 additional | 1034 | @code{GNUNET_TESTING_system_create_with_portrange()}. This function is |
996 | parameters --- the start and end of the port range to use. | 1035 | similar to @code{GNUNET_TESTING_system_create()} except that it take 2 |
1036 | additional parameters --- the start and end of the port range to use. | ||
997 | 1037 | ||
998 | A TESTING system is destroyed with the funciton | 1038 | A TESTING system is destroyed with the funciton |
999 | @code{GNUNET_TESTING_system_destory()}. This function takes the handle of the | 1039 | @code{GNUNET_TESTING_system_destory()}. This function takes the handle of |
1000 | system and a flag to remove the files created in the directory used to generate | 1040 | the system and a flag to remove the files created in the directory used |
1001 | configurations. | 1041 | to generate configurations. |
1002 | 1042 | ||
1003 | A peer is created with the function @code{GNUNET_TESTING_peer_configure()}. | 1043 | A peer is created with the function |
1004 | This functions takes the system handle, a configuration template from which the | 1044 | @code{GNUNET_TESTING_peer_configure()}. This functions takes the system |
1005 | configuration for the peer is auto-generated and the index from where the | 1045 | handle, a configuration template from which the configuration for the peer |
1006 | hostkey for the peer has to be copied from. When successfull, this function | 1046 | is auto-generated and the index from where the hostkey for the peer has to |
1007 | returs a handle to the peer which can be used to start and stop it and to | 1047 | be copied from. When successfull, this function returs a handle to the |
1008 | obtain the identity of the peer. If unsuccessful, a NULL pointer is returned | 1048 | peer which can be used to start and stop it and to obtain the identity of |
1009 | with an error message. This function handles the generated configuration to | 1049 | the peer. If unsuccessful, a NULL pointer is returned with an error |
1010 | have non-conflicting ports and paths. | 1050 | message. This function handles the generated configuration to have |
1051 | non-conflicting ports and paths. | ||
1011 | 1052 | ||
1012 | Peers can be started and stopped by calling the functions | 1053 | Peers can be started and stopped by calling the functions |
1013 | @code{GNUNET_TESTING_peer_start()} and @code{GNUNET_TESTING_peer_stop()} | 1054 | @code{GNUNET_TESTING_peer_start()} and @code{GNUNET_TESTING_peer_stop()} |
1014 | respectively. A peer can be destroyed by calling the function | 1055 | respectively. A peer can be destroyed by calling the function |
1015 | @code{GNUNET_TESTING_peer_destroy}. When a peer is destroyed, the ports and | 1056 | @code{GNUNET_TESTING_peer_destroy}. When a peer is destroyed, the ports |
1016 | paths in allocated in its configuration are reclaimed for usage in new | 1057 | and paths in allocated in its configuration are reclaimed for usage in new |
1017 | peers. | 1058 | peers. |
1018 | 1059 | ||
1019 | @c *************************************************************************** | 1060 | @c *********************************************************************** |
1020 | @node Finer control over peer stop | 1061 | @node Finer control over peer stop |
1021 | @subsection Finer control over peer stop | 1062 | @subsection Finer control over peer stop |
1022 | 1063 | ||
1023 | Using @code{GNUNET_TESTING_peer_stop()} is normally fine for testcases. | 1064 | Using @code{GNUNET_TESTING_peer_stop()} is normally fine for testcases. |
1024 | However, calling this function for each peer is inefficient when trying to | 1065 | However, calling this function for each peer is inefficient when trying to |
1025 | shutdown multiple peers as this function sends the termination signal to the | 1066 | shutdown multiple peers as this function sends the termination signal to |
1026 | given peer process and waits for it to terminate. It would be faster in this | 1067 | the given peer process and waits for it to terminate. It would be faster |
1027 | case to send the termination signals to the peers first and then wait on them. | 1068 | in this case to send the termination signals to the peers first and then |
1028 | This is accomplished by the functions @code{GNUNET_TESTING_peer_kill()} which | 1069 | wait on them. This is accomplished by the functions |
1029 | sends a termination signal to the peer, and the function | 1070 | @code{GNUNET_TESTING_peer_kill()} which sends a termination signal to the |
1030 | @code{GNUNET_TESTING_peer_wait()} which waits on the peer. | 1071 | peer, and the function @code{GNUNET_TESTING_peer_wait()} which waits on |
1031 | 1072 | the peer. | |
1032 | Further finer control can be achieved by choosing to stop a peer asynchronously | 1073 | |
1033 | with the function @code{GNUNET_TESTING_peer_stop_async()}. This function takes | 1074 | Further finer control can be achieved by choosing to stop a peer |
1034 | a callback parameter and a closure for it in addition to the handle to the peer | 1075 | asynchronously with the function @code{GNUNET_TESTING_peer_stop_async()}. |
1035 | to stop. The callback function is called with the given closure when the peer | 1076 | This function takes a callback parameter and a closure for it in addition |
1036 | is stopped. Using this function eliminates blocking while waiting for the peer | 1077 | to the handle to the peer to stop. The callback function is called with |
1037 | to terminate. | 1078 | the given closure when the peer is stopped. Using this function |
1079 | eliminates blocking while waiting for the peer to terminate. | ||
1038 | 1080 | ||
1039 | An asynchronous peer stop can be cancelled by calling the function | 1081 | An asynchronous peer stop can be cancelled by calling the function |
1040 | @code{GNUNET_TESTING_peer_stop_async_cancel()}. Note that calling this function | 1082 | @code{GNUNET_TESTING_peer_stop_async_cancel()}. Note that calling this |
1041 | does not prevent the peer from terminating if the termination signal has | 1083 | function does not prevent the peer from terminating if the termination |
1042 | already been sent to it. It does, however, cancels the callback to be called | 1084 | signal has already been sent to it. It does, however, cancels the |
1043 | when the peer is stopped. | 1085 | callback to be called when the peer is stopped. |
1044 | 1086 | ||
1045 | @c *************************************************************************** | 1087 | @c *********************************************************************** |
1046 | @node Helper functions | 1088 | @node Helper functions |
1047 | @subsection Helper functions | 1089 | @subsection Helper functions |
1048 | 1090 | ||
1049 | Most of the testcases can benefit from an abstraction which configures a peer | 1091 | Most of the testcases can benefit from an abstraction which configures a |
1050 | and starts it. This is provided by the function | 1092 | peer and starts it. This is provided by the function |
1051 | @code{GNUNET_TESTING_peer_run()}. This function takes the testing directory | 1093 | @code{GNUNET_TESTING_peer_run()}. This function takes the testing |
1052 | pathname, a configuration template, a callback and its closure. This function | 1094 | directory pathname, a configuration template, a callback and its closure. |
1053 | creates a peer in the given testing directory by using the configuration | 1095 | This function creates a peer in the given testing directory by using the |
1054 | template, starts the peer and calls the given callback with the given closure. | 1096 | configuration template, starts the peer and calls the given callback with |
1055 | 1097 | the given closure. | |
1056 | The function @code{GNUNET_TESTING_peer_run()} starts the ARM service of the | 1098 | |
1057 | peer which starts the rest of the configured services. A similar function | 1099 | The function @code{GNUNET_TESTING_peer_run()} starts the ARM service of |
1058 | @code{GNUNET_TESTING_service_run} can be used to just start a single service of | 1100 | the peer which starts the rest of the configured services. A similar |
1059 | a peer. In this case, the peer's ARM service is not started; instead, only the | 1101 | function @code{GNUNET_TESTING_service_run} can be used to just start a |
1060 | given service is run. | 1102 | single service of a peer. In this case, the peer's ARM service is not |
1061 | 1103 | started; instead, only the given service is run. | |
1062 | @c *************************************************************************** | 1104 | |
1105 | @c *********************************************************************** | ||
1063 | @node Testing with multiple processes | 1106 | @node Testing with multiple processes |
1064 | @subsection Testing with multiple processes | 1107 | @subsection Testing with multiple processes |
1065 | 1108 | ||
1066 | When testing GNUnet, the splitting of the code into a services and clients | 1109 | When testing GNUnet, the splitting of the code into a services and clients |
1067 | often complicates testing. The solution to this is to have the testcase fork | 1110 | often complicates testing. The solution to this is to have the testcase |
1068 | @code{gnunet-service-arm}, ask it to start the required server and daemon | 1111 | fork @code{gnunet-service-arm}, ask it to start the required server and |
1069 | processes and then execute appropriate client actions (to test the client APIs | 1112 | daemon processes and then execute appropriate client actions (to test the |
1070 | or the core module or both). If necessary, multiple ARM services can be forked | 1113 | client APIs or the core module or both). If necessary, multiple ARM |
1071 | using different ports (!) to simulate a network. However, most of the time only | 1114 | services can be forked using different ports (!) to simulate a network. |
1072 | one ARM process is needed. Note that on exit, the testcase should shutdown ARM | 1115 | However, most of the time only one ARM process is needed. Note that on |
1073 | with a @code{TERM} signal (to give it the chance to cleanly stop its child | 1116 | exit, the testcase should shutdown ARM with a @code{TERM} signal (to give |
1074 | processes). | 1117 | it the chance to cleanly stop its child processes). |
1075 | 1118 | ||
1076 | The following code illustrates spawning and killing an ARM process from a | 1119 | The following code illustrates spawning and killing an ARM process from a |
1077 | testcase: | 1120 | testcase: |
1121 | |||
1078 | @example | 1122 | @example |
1079 | static void run (void *cls, char *const *args, const char | 1123 | static void run (void *cls, char *const *args, const char |
1080 | *cfgfile, const struct GNUNET_CONFIGURATION_Handle *cfg) @{ struct | 1124 | *cfgfile, const struct GNUNET_CONFIGURATION_Handle *cfg) @{ struct |
@@ -1090,43 +1134,47 @@ GNUNET_PROGRAM_run (argc, argv, "NAME-OF-TEST", "nohelp", options, &run, cls); | |||
1090 | 1134 | ||
1091 | 1135 | ||
1092 | An alternative way that works well to test plugins is to implement a | 1136 | An alternative way that works well to test plugins is to implement a |
1093 | mock-version of the environment that the plugin expects and then to simply load | 1137 | mock-version of the environment that the plugin expects and then to |
1094 | the plugin directly. | 1138 | simply load the plugin directly. |
1095 | 1139 | ||
1096 | @c *************************************************************************** | 1140 | @c *********************************************************************** |
1097 | @node Performance regression analysis with Gauger | 1141 | @node Performance regression analysis with Gauger |
1098 | @section Performance regression analysis with Gauger | 1142 | @section Performance regression analysis with Gauger |
1099 | 1143 | ||
1100 | To help avoid performance regressions, GNUnet uses Gauger. Gauger is a simple | 1144 | To help avoid performance regressions, GNUnet uses Gauger. Gauger is a |
1101 | logging tool that allows remote hosts to send performance data to a central | 1145 | simple logging tool that allows remote hosts to send performance data to |
1102 | server, where this data can be analyzed and visualized. Gauger shows graphs of | 1146 | a central server, where this data can be analyzed and visualized. Gauger |
1103 | the repository revisions and the performace data recorded for each revision, so | 1147 | shows graphs of the repository revisions and the performace data recorded |
1104 | sudden performance peaks or drops can be identified and linked to a specific | 1148 | for each revision, so sudden performance peaks or drops can be identified |
1105 | revision number. | 1149 | and linked to a specific revision number. |
1106 | 1150 | ||
1107 | In the case of GNUnet, the buildbots log the performance data obtained during | 1151 | In the case of GNUnet, the buildbots log the performance data obtained |
1108 | the tests after each build. The data can be accesed on GNUnet's Gauger page. | 1152 | during the tests after each build. The data can be accesed on GNUnet's |
1109 | 1153 | Gauger page. | |
1110 | The menu on the left allows to select either the results of just one build bot | 1154 | |
1111 | (under "Hosts") or review the data from all hosts for a given test result | 1155 | The menu on the left allows to select either the results of just one |
1112 | (under "Metrics"). In case of very different absolute value of the results, for | 1156 | build bot (under "Hosts") or review the data from all hosts for a given |
1113 | instance arm vs. amd64 machines, the option "Normalize" on a metric view can | 1157 | test result (under "Metrics"). In case of very different absolute value |
1114 | help to get an idea about the performance evolution across all hosts. | 1158 | of the results, for instance arm vs. amd64 machines, the option |
1115 | 1159 | "Normalize" on a metric view can help to get an idea about the | |
1116 | Using Gauger in GNUnet and having the performance of a module tracked over time | 1160 | performance evolution across all hosts. |
1117 | is very easy. First of course, the testcase must generate some consistent | 1161 | |
1118 | metric, which makes sense to have logged. Highly volatile or random dependant | 1162 | Using Gauger in GNUnet and having the performance of a module tracked over |
1119 | metrics probably are not ideal candidates for meaningful regression detection. | 1163 | time is very easy. First of course, the testcase must generate some |
1120 | 1164 | consistent metric, which makes sense to have logged. Highly volatile or | |
1121 | To start logging any value, just include @code{gauger.h} in your testcase code. | 1165 | random dependant metrics probably are not ideal candidates for meaningful |
1122 | Then, use the macro @code{GAUGER()} to make the buildbots log whatever value is | 1166 | regression detection. |
1123 | of interest for you to @code{gnunet.org}'s Gauger server. No setup is necessary | 1167 | |
1124 | as most buildbots have already everything in place and new metrics are created | 1168 | To start logging any value, just include @code{gauger.h} in your testcase |
1125 | on demand. To delete a metric, you need to contact a member of the GNUnet | 1169 | code. Then, use the macro @code{GAUGER()} to make the buildbots log |
1126 | development team (a file will need to be removed manually from the respective | 1170 | whatever value is of interest for you to @code{gnunet.org}'s Gauger |
1127 | directory). | 1171 | server. No setup is necessary as most buildbots have already everything |
1172 | in place and new metrics are created on demand. To delete a metric, you | ||
1173 | need to contact a member of the GNUnet development team (a file will need | ||
1174 | to be removed manually from the respective directory). | ||
1128 | 1175 | ||
1129 | The code in the test should look like this: | 1176 | The code in the test should look like this: |
1177 | |||
1130 | @example | 1178 | @example |
1131 | [other includes] | 1179 | [other includes] |
1132 | #include <gauger.h> | 1180 | #include <gauger.h> |
@@ -1139,13 +1187,14 @@ int main (int argc, char *argv[]) @{ | |||
1139 | 1187 | ||
1140 | 1188 | ||
1141 | Where: | 1189 | Where: |
1190 | |||
1142 | @table @asis | 1191 | @table @asis |
1143 | 1192 | ||
1144 | @item @strong{YOUR_MODULE} is a category in the gauger page and should be the | 1193 | @item @strong{YOUR_MODULE} is a category in the gauger page and should be |
1145 | name of the module or subsystem like "Core" or "DHT" | 1194 | the name of the module or subsystem like "Core" or "DHT" |
1146 | @item @strong{METRIC} is | 1195 | @item @strong{METRIC} is |
1147 | the name of the metric being collected and should be concise and descriptive, | 1196 | the name of the metric being collected and should be concise and |
1148 | like "PUT operations in sqlite-datastore". | 1197 | descriptive, like "PUT operations in sqlite-datastore". |
1149 | @item @strong{value} is the value | 1198 | @item @strong{value} is the value |
1150 | of the metric that is logged for this run. | 1199 | of the metric that is logged for this run. |
1151 | @item @strong{UNIT} is the unit in | 1200 | @item @strong{UNIT} is the unit in |
@@ -1155,7 +1204,7 @@ which the value is measured, for instance "kb/s" or "kb of RAM/node". | |||
1155 | If you wish to use Gauger for your own project, you can grab a copy of the | 1204 | If you wish to use Gauger for your own project, you can grab a copy of the |
1156 | latest stable release or check out Gauger's Subversion repository. | 1205 | latest stable release or check out Gauger's Subversion repository. |
1157 | 1206 | ||
1158 | @c *************************************************************************** | 1207 | @c *********************************************************************** |
1159 | @node GNUnet's TESTBED Subsystem | 1208 | @node GNUnet's TESTBED Subsystem |
1160 | @section GNUnet's TESTBED Subsystem | 1209 | @section GNUnet's TESTBED Subsystem |
1161 | 1210 | ||
@@ -1166,39 +1215,46 @@ The architecture of the testbed module is divided into the following: | |||
1166 | @itemize @bullet | 1215 | @itemize @bullet |
1167 | 1216 | ||
1168 | @item Testbed API: An API which is used by the testing driver programs. It | 1217 | @item Testbed API: An API which is used by the testing driver programs. It |
1169 | provides with functions for creating, destroying, starting, stopping peers, | 1218 | provides with functions for creating, destroying, starting, stopping |
1170 | etc. | 1219 | peers, etc. |
1171 | 1220 | ||
1172 | @item Testbed service (controller): A service which is started through the | 1221 | @item Testbed service (controller): A service which is started through the |
1173 | Testbed API. This service handles operations to create, destroy, start, stop | 1222 | Testbed API. This service handles operations to create, destroy, start, |
1174 | peers, connect them, modify their configurations. | 1223 | stop peers, connect them, modify their configurations. |
1175 | 1224 | ||
1176 | @item Testbed helper: When a controller has to be started on a host, the | 1225 | @item Testbed helper: When a controller has to be started on a host, the |
1177 | testbed API starts the testbed helper on that host which in turn starts the | 1226 | testbed API starts the testbed helper on that host which in turn starts |
1178 | controller. The testbed helper receives a configuration for the controller | 1227 | the controller. The testbed helper receives a configuration for the |
1179 | through its stdin and changes it to ensure the controller doesn't run into any | 1228 | controller through its stdin and changes it to ensure the controller |
1180 | port conflict on that host. | 1229 | doesn't run into any port conflict on that host. |
1181 | @end itemize | 1230 | @end itemize |
1182 | 1231 | ||
1183 | 1232 | ||
1184 | The testbed service (controller) is different from the other GNUnet services in | 1233 | The testbed service (controller) is different from the other GNUnet |
1185 | that it is not started by ARM and is not supposed to be run as a daemon. It is | 1234 | services in that it is not started by ARM and is not supposed to be run |
1186 | started by the testbed API through a testbed helper. In a typical scenario | 1235 | as a daemon. It is started by the testbed API through a testbed helper. |
1187 | involving multiple hosts, a controller is started on each host. Controllers | 1236 | In a typical scenario involving multiple hosts, a controller is started |
1188 | take up the actual task of creating peers, starting and stopping them on the | 1237 | on each host. Controllers take up the actual task of creating peers, |
1189 | hosts they run. | 1238 | starting and stopping them on the hosts they run. |
1190 | 1239 | ||
1191 | While running deployments on a single localhost the testbed API starts the | 1240 | While running deployments on a single localhost the testbed API starts the |
1192 | testbed helper directly as a child process. When running deployments on remote | 1241 | testbed helper directly as a child process. When running deployments on |
1193 | hosts the testbed API starts Testbed Helpers on each remote host through remote | 1242 | remote hosts the testbed API starts Testbed Helpers on each remote host |
1194 | shell. By default testbed API uses SSH as a remote shell. This can be changed | 1243 | through remote shell. By default testbed API uses SSH as a remote shell. |
1195 | by setting the environmental variable GNUNET_TESTBED_RSH_CMD to the required | 1244 | This can be changed by setting the environmental variable |
1196 | remote shell program. This variable can also contain parameters which are to be | 1245 | GNUNET_TESTBED_RSH_CMD to the required remote shell program. This |
1197 | passed to the remote shell program. For e.g:@ @code{@ export | 1246 | variable can also contain parameters which are to be passed to the remote |
1198 | GNUNET_TESTBED_RSH_CMD="ssh -o BatchMode=yes -o | 1247 | shell program. For e.g: |
1199 | NoHostAuthenticationForLocalhost=yes %h"@ }@ Substitutions are allowed int the | 1248 | |
1200 | above command string also allows for substitions. through placemarks which | 1249 | @example |
1201 | begin with a `%'. At present the following substitutions are supported | 1250 | export GNUNET_TESTBED_RSH_CMD="ssh -o BatchMode=yes \ |
1251 | -o NoHostAuthenticationForLocalhost=yes %h"@ | ||
1252 | @end example | ||
1253 | |||
1254 | Substitutions are allowed int the above command string also allows for | ||
1255 | substitions. through placemarks which begin with a `%'. At present the | ||
1256 | following substitutions are supported | ||
1257 | |||
1202 | @itemize @bullet | 1258 | @itemize @bullet |
1203 | @item | 1259 | @item |
1204 | %h: hostname | 1260 | %h: hostname |
@@ -1208,41 +1264,56 @@ begin with a `%'. At present the following substitutions are supported | |||
1208 | %p: port | 1264 | %p: port |
1209 | @end itemize | 1265 | @end itemize |
1210 | 1266 | ||
1211 | Note that the substitution placemark is replaced only when the corresponding | 1267 | Note that the substitution placemark is replaced only when the |
1212 | field is available and only once. Specifying @code{%u@@%h} doesn't work either. | 1268 | corresponding field is available and only once. Specifying @code{%u@@%h} |
1213 | If you want to user username substitutions for SSH use the argument @code{-l} | 1269 | doesn't work either. If you want to user username substitutions for SSH |
1214 | before the username substitution. Ex: @code{ssh -l %u -p %p %h} | 1270 | use the argument @code{-l} before the username substitution. |
1271 | Ex: @code{ssh -l %u -p %p %h} | ||
1215 | 1272 | ||
1216 | The testbed API and the helper communicate through the helpers stdin and | 1273 | The testbed API and the helper communicate through the helpers stdin and |
1217 | stdout. As the helper is started through a remote shell on remote hosts any | 1274 | stdout. As the helper is started through a remote shell on remote hosts |
1218 | output messages from the remote shell interfere with the communication and | 1275 | any output messages from the remote shell interfere with the communication |
1219 | results in a failure while starting the helper. For this reason, it is | 1276 | and results in a failure while starting the helper. For this reason, it is |
1220 | suggested to use flags to make the remote shells produce no output messages and | 1277 | suggested to use flags to make the remote shells produce no output |
1221 | to have password-less logins. The default remote shell, SSH, the default | 1278 | messages and to have password-less logins. The default remote shell, SSH, |
1222 | options are "-o BatchMode=yes -o NoHostBasedAuthenticationForLocalhost=yes". | 1279 | the default options are: |
1280 | |||
1281 | @example | ||
1282 | -o BatchMode=yes -o NoHostBasedAuthenticationForLocalhost=yes" | ||
1283 | @end example | ||
1284 | |||
1223 | Password-less logins should be ensured by using SSH keys. | 1285 | Password-less logins should be ensured by using SSH keys. |
1224 | 1286 | ||
1225 | Since the testbed API executes the remote shell as a non-interactive shell, | 1287 | Since the testbed API executes the remote shell as a non-interactive |
1226 | certain scripts like .bashrc, .profiler may not be executed. If this is the | 1288 | shell, certain scripts like .bashrc, .profiler may not be executed. If |
1227 | case testbed API can be forced to execute an interactive shell by setting up | 1289 | this is the case testbed API can be forced to execute an interactive |
1228 | the environmental variable `GNUNET_TESTBED_RSH_CMD_SUFFIX' to a shell program. | 1290 | shell by setting up the environmental variable |
1229 | An example could be:@ @code{@ export GNUNET_TESTBED_RSH_CMD_SUFFIX="sh -lc"@ }@ | 1291 | `GNUNET_TESTBED_RSH_CMD_SUFFIX' to a shell program. |
1230 | The testbed API will then execute the remote shell program as: @code{ | 1292 | An example could be: |
1231 | $GNUNET_TESTBED_RSH_CMD -p $port $dest $GNUNET_TESTBED_RSH_CMD_SUFFIX | 1293 | |
1232 | gnunet-helper-testbed } | 1294 | @example |
1233 | 1295 | export GNUNET_TESTBED_RSH_CMD_SUFFIX="sh -lc" | |
1234 | On some systems, problems may arise while starting testbed helpers if GNUnet is | 1296 | @end example |
1235 | installed into a custom location since the helper may not be found in the | 1297 | |
1236 | standard path. This can be addressed by setting the variable | 1298 | The testbed API will then execute the remote shell program as: |
1237 | `HELPER_BINARY_PATH' to the path of the testbed helper. Testbed API will then | 1299 | |
1238 | use this path to start helper binaries both locally and remotely. | 1300 | @example |
1301 | $GNUNET_TESTBED_RSH_CMD -p $port $dest $GNUNET_TESTBED_RSH_CMD_SUFFIX \ | ||
1302 | gnunet-helper-testbed | ||
1303 | @end example | ||
1304 | |||
1305 | On some systems, problems may arise while starting testbed helpers if | ||
1306 | GNUnet is installed into a custom location since the helper may not be | ||
1307 | found in the standard path. This can be addressed by setting the variable | ||
1308 | `HELPER_BINARY_PATH' to the path of the testbed helper. Testbed API will | ||
1309 | then use this path to start helper binaries both locally and remotely. | ||
1239 | 1310 | ||
1240 | Testbed API can accessed by including "gnunet_testbed_service.h" file and | 1311 | Testbed API can accessed by including "gnunet_testbed_service.h" file and |
1241 | linking with -lgnunettestbed. | 1312 | linking with -lgnunettestbed. |
1242 | 1313 | ||
1243 | 1314 | ||
1244 | 1315 | ||
1245 | @c *************************************************************************** | 1316 | @c *********************************************************************** |
1246 | @menu | 1317 | @menu |
1247 | * Supported Topologies:: | 1318 | * Supported Topologies:: |
1248 | * Hosts file format:: | 1319 | * Hosts file format:: |
@@ -1255,56 +1326,60 @@ linking with -lgnunettestbed. | |||
1255 | @node Supported Topologies | 1326 | @node Supported Topologies |
1256 | @subsection Supported Topologies | 1327 | @subsection Supported Topologies |
1257 | 1328 | ||
1258 | While testing multi-peer deployments, it is often needed that the peers are | 1329 | While testing multi-peer deployments, it is often needed that the peers |
1259 | connected in some topology. This requirement is addressed by the function | 1330 | are connected in some topology. This requirement is addressed by the |
1260 | @code{GNUNET_TESTBED_overlay_connect()} which connects any given two peers in | 1331 | function @code{GNUNET_TESTBED_overlay_connect()} which connects any given |
1261 | the testbed. | 1332 | two peers in the testbed. |
1262 | 1333 | ||
1263 | The API also provides a helper function | 1334 | The API also provides a helper function |
1264 | @code{GNUNET_TESTBED_overlay_configure_topology()} to connect a given set of | 1335 | @code{GNUNET_TESTBED_overlay_configure_topology()} to connect a given set |
1265 | peers in any of the following supported topologies: | 1336 | of peers in any of the following supported topologies: |
1337 | |||
1266 | @itemize @bullet | 1338 | @itemize @bullet |
1267 | 1339 | ||
1268 | @item @code{GNUNET_TESTBED_TOPOLOGY_CLIQUE}: All peers are connected with each | 1340 | @item @code{GNUNET_TESTBED_TOPOLOGY_CLIQUE}: All peers are connected with |
1269 | other | 1341 | each other |
1270 | 1342 | ||
1271 | @item @code{GNUNET_TESTBED_TOPOLOGY_LINE}: Peers are connected to form a line | 1343 | @item @code{GNUNET_TESTBED_TOPOLOGY_LINE}: Peers are connected to form a |
1344 | line | ||
1272 | 1345 | ||
1273 | @item @code{GNUNET_TESTBED_TOPOLOGY_RING}: Peers are connected to form a ring | 1346 | @item @code{GNUNET_TESTBED_TOPOLOGY_RING}: Peers are connected to form a |
1274 | topology | 1347 | ring topology |
1275 | 1348 | ||
1276 | @item @code{GNUNET_TESTBED_TOPOLOGY_2D_TORUS}: Peers are connected to form a 2 | 1349 | @item @code{GNUNET_TESTBED_TOPOLOGY_2D_TORUS}: Peers are connected to |
1277 | dimensional torus topology. The number of peers may not be a perfect square, in | 1350 | form a 2 dimensional torus topology. The number of peers may not be a |
1278 | that case the resulting torus may not have the uniform poloidal and toroidal | 1351 | perfect square, in that case the resulting torus may not have the uniform |
1279 | lengths | 1352 | poloidal and toroidal lengths |
1280 | 1353 | ||
1281 | @item @code{GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI}: Topology is generated to form | 1354 | @item @code{GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI}: Topology is generated |
1282 | a random graph. The number of links to be present should be given | 1355 | to form a random graph. The number of links to be present should be given |
1283 | 1356 | ||
1284 | @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD}: Peers are connected to form a | 1357 | @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD}: Peers are connected to |
1285 | 2D Torus with some random links among them. The number of random links are to | 1358 | form a 2D Torus with some random links among them. The number of random |
1286 | be given | 1359 | links are to be given |
1287 | 1360 | ||
1288 | @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING}: Peers are connected to | 1361 | @item @code{GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING}: Peers are |
1289 | form a ring with some random links among them. The number of random links are | 1362 | connected to form a ring with some random links among them. The number of |
1290 | to be given | 1363 | random links are to be given |
1291 | 1364 | ||
1292 | @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a topology | 1365 | @item @code{GNUNET_TESTBED_TOPOLOGY_SCALE_FREE}: Connects peers in a |
1293 | where peer connectivity follows power law - new peers are connected with high | 1366 | topology where peer connectivity follows power law - new peers are |
1294 | probabililty to well connected peers. See Emergence of Scaling in Random | 1367 | connected with high probabililty to well connected peers. |
1295 | Networks. Science 286, 509-512, 1999. | 1368 | @footnote{See Emergence of Scaling in Random Networks. Science 286, |
1369 | 509-512, 1999.} | ||
1296 | 1370 | ||
1297 | @item @code{GNUNET_TESTBED_TOPOLOGY_FROM_FILE}: The topology information is | 1371 | @item @code{GNUNET_TESTBED_TOPOLOGY_FROM_FILE}: The topology information |
1298 | loaded from a file. The path to the file has to be given. See Topology file | 1372 | is loaded from a file. The path to the file has to be given. See Topology |
1299 | format for the format of this file. | 1373 | file format for the format of this file. |
1300 | 1374 | ||
1301 | @item @code{GNUNET_TESTBED_TOPOLOGY_NONE}: No topology | 1375 | @item @code{GNUNET_TESTBED_TOPOLOGY_NONE}: No topology |
1302 | @end itemize | 1376 | @end itemize |
1303 | 1377 | ||
1304 | 1378 | ||
1305 | The above supported topologies can be specified respectively by setting the | 1379 | The above supported topologies can be specified respectively by setting |
1306 | variable @code{OVERLAY_TOPOLOGY} to the following values in the configuration | 1380 | the variable @code{OVERLAY_TOPOLOGY} to the following values in the |
1307 | passed to Testbed API functions @code{GNUNET_TESTBED_test_run()} and | 1381 | configuration passed to Testbed API functions |
1382 | @code{GNUNET_TESTBED_test_run()} and | ||
1308 | @code{GNUNET_TESTBED_run()}: | 1383 | @code{GNUNET_TESTBED_run()}: |
1309 | @itemize @bullet | 1384 | @itemize @bullet |
1310 | @item @code{CLIQUE} | 1385 | @item @code{CLIQUE} |
@@ -1322,114 +1397,115 @@ passed to Testbed API functions @code{GNUNET_TESTBED_test_run()} and | |||
1322 | 1397 | ||
1323 | Topologies @code{RANDOM}, @code{SMALL_WORLD} and @code{SMALL_WORLD_RING} | 1398 | Topologies @code{RANDOM}, @code{SMALL_WORLD} and @code{SMALL_WORLD_RING} |
1324 | require the option @code{OVERLAY_RANDOM_LINKS} to be set to the number of | 1399 | require the option @code{OVERLAY_RANDOM_LINKS} to be set to the number of |
1325 | random links to be generated in the configuration. The option will be ignored | 1400 | random links to be generated in the configuration. The option will be |
1326 | for the rest of the topologies. | 1401 | ignored for the rest of the topologies. |
1327 | 1402 | ||
1328 | Topology @code{SCALE_FREE} requires the options @code{SCALE_FREE_TOPOLOGY_CAP} | 1403 | Topology @code{SCALE_FREE} requires the options |
1329 | to be set to the maximum number of peers which can connect to a peer and | 1404 | @code{SCALE_FREE_TOPOLOGY_CAP} to be set to the maximum number of peers |
1330 | @code{SCALE_FREE_TOPOLOGY_M} to be set to how many peers a peer should be | 1405 | which can connect to a peer and @code{SCALE_FREE_TOPOLOGY_M} to be set to |
1331 | atleast connected to. | 1406 | how many peers a peer should be atleast connected to. |
1332 | 1407 | ||
1333 | Similarly, the topology @code{FROM_FILE} requires the option | 1408 | Similarly, the topology @code{FROM_FILE} requires the option |
1334 | @code{OVERLAY_TOPOLOGY_FILE} to contain the path of the file containing the | 1409 | @code{OVERLAY_TOPOLOGY_FILE} to contain the path of the file containing |
1335 | topology information. This option is ignored for the rest of the topologies. | 1410 | the topology information. This option is ignored for the rest of the |
1336 | See Topology file format for the format of this file. | 1411 | topologies. See Topology file format for the format of this file. |
1337 | 1412 | ||
1338 | @c *************************************************************************** | 1413 | @c *********************************************************************** |
1339 | @node Hosts file format | 1414 | @node Hosts file format |
1340 | @subsection Hosts file format | 1415 | @subsection Hosts file format |
1341 | 1416 | ||
1342 | The testbed API offers the function GNUNET_TESTBED_hosts_load_from_file() to | 1417 | The testbed API offers the function GNUNET_TESTBED_hosts_load_from_file() |
1343 | load from a given file details about the hosts which testbed can use for | 1418 | to load from a given file details about the hosts which testbed can use |
1344 | deploying peers. This function is useful to keep the data about hosts separate | 1419 | for deploying peers. This function is useful to keep the data about hosts |
1345 | instead of hard coding them in code. | 1420 | separate instead of hard coding them in code. |
1346 | 1421 | ||
1347 | Another helper function from testbed API, GNUNET_TESTBED_run() also takes a | 1422 | Another helper function from testbed API, GNUNET_TESTBED_run() also takes |
1348 | hosts file name as its parameter. It uses the above function to populate the | 1423 | a hosts file name as its parameter. It uses the above function to |
1349 | hosts data structures and start controllers to deploy peers. | 1424 | populate the hosts data structures and start controllers to deploy peers. |
1350 | 1425 | ||
1351 | These functions require the hosts file to be of the following format: | 1426 | These functions require the hosts file to be of the following format: |
1352 | @itemize @bullet | 1427 | @itemize @bullet |
1353 | @item Each line is interpreted to have details about a host | 1428 | @item Each line is interpreted to have details about a host |
1354 | @item Host details should include the username to use for logging into the | 1429 | @item Host details should include the username to use for logging into the |
1355 | host, the hostname of the host and the port number to use for the remote shell | 1430 | host, the hostname of the host and the port number to use for the remote |
1356 | program. All thee values should be given. | 1431 | shell program. All thee values should be given. |
1357 | @item These details should be given in the following format: | 1432 | @item These details should be given in the following format: |
1358 | @code{<username>@@<hostname>:<port>} | 1433 | @code{<username>@@<hostname>:<port>} |
1359 | @end itemize | 1434 | @end itemize |
1360 | 1435 | ||
1361 | Note that having canonical hostnames may cause problems while resolving the IP | 1436 | Note that having canonical hostnames may cause problems while resolving |
1362 | addresses (See this bug). Hence it is advised to provide the hosts' IP | 1437 | the IP addresses (See this bug). Hence it is advised to provide the hosts' |
1363 | numerical addresses as hostnames whenever possible. | 1438 | IP numerical addresses as hostnames whenever possible. |
1364 | 1439 | ||
1365 | @c *************************************************************************** | 1440 | @c *********************************************************************** |
1366 | @node Topology file format | 1441 | @node Topology file format |
1367 | @subsection Topology file format | 1442 | @subsection Topology file format |
1368 | 1443 | ||
1369 | A topology file describes how peers are to be connected. It should adhere to | 1444 | A topology file describes how peers are to be connected. It should adhere |
1370 | the following format for testbed to parse it correctly. | 1445 | to the following format for testbed to parse it correctly. |
1371 | 1446 | ||
1372 | Each line should begin with the target peer id. This should be followed by a | 1447 | Each line should begin with the target peer id. This should be followed by |
1373 | colon(`:') and origin peer ids seperated by `|'. All spaces except for newline | 1448 | a colon(`:') and origin peer ids seperated by `|'. All spaces except for |
1374 | characters are ignored. The API will then try to connect each origin peer to | 1449 | newline characters are ignored. The API will then try to connect each |
1375 | the target peer. | 1450 | origin peer to the target peer. |
1376 | 1451 | ||
1377 | For example, the following file will result in 5 overlay connections: [2->1], | 1452 | For example, the following file will result in 5 overlay connections: |
1378 | [3->1],[4->3], [0->3], [2->0]@ @code{@ 1:2|3@ 3:4| 0@ 0: 2@ } | 1453 | [2->1], [3->1],[4->3], [0->3], [2->0]@ @code{@ 1:2|3@ 3:4| 0@ 0: 2@ } |
1379 | 1454 | ||
1380 | @c *************************************************************************** | 1455 | @c *********************************************************************** |
1381 | @node Testbed Barriers | 1456 | @node Testbed Barriers |
1382 | @subsection Testbed Barriers | 1457 | @subsection Testbed Barriers |
1383 | 1458 | ||
1384 | The testbed subsystem's barriers API facilitates coordination among the peers | 1459 | The testbed subsystem's barriers API facilitates coordination among the |
1385 | run by the testbed and the experiment driver. The concept is similar to the | 1460 | peers run by the testbed and the experiment driver. The concept is |
1386 | barrier synchronisation mechanism found in parallel programming or | 1461 | similar to the barrier synchronisation mechanism found in parallel |
1387 | multi-threading paradigms - a peer waits at a barrier upon reaching it until | 1462 | programming or multi-threading paradigms - a peer waits at a barrier upon |
1388 | the barrier is reached by a predefined number of peers. This predefined number | 1463 | reaching it until the barrier is reached by a predefined number of peers. |
1389 | of peers required to cross a barrier is also called quorum. We say a peer has | 1464 | This predefined number of peers required to cross a barrier is also called |
1390 | reached a barrier if the peer is waiting for the barrier to be crossed. | 1465 | quorum. We say a peer has reached a barrier if the peer is waiting for the |
1391 | Similarly a barrier is said to be reached if the required quorum of peers reach | 1466 | barrier to be crossed. Similarly a barrier is said to be reached if the |
1392 | the barrier. A barrier which is reached is deemed as crossed after all the | 1467 | required quorum of peers reach the barrier. A barrier which is reached is |
1393 | peers waiting on it are notified. | 1468 | deemed as crossed after all the peers waiting on it are notified. |
1394 | 1469 | ||
1395 | The barriers API provides the following functions: | 1470 | The barriers API provides the following functions: |
1396 | @itemize @bullet | 1471 | @itemize @bullet |
1397 | @item @strong{@code{GNUNET_TESTBED_barrier_init()}:} function to initialse a | 1472 | @item @strong{@code{GNUNET_TESTBED_barrier_init()}:} function to |
1398 | barrier in the experiment | 1473 | initialse a barrier in the experiment |
1399 | @item @strong{@code{GNUNET_TESTBED_barrier_cancel()}:} function to cancel a | 1474 | @item @strong{@code{GNUNET_TESTBED_barrier_cancel()}:} function to cancel |
1400 | barrier which has been initialised before | 1475 | a barrier which has been initialised before |
1401 | @item @strong{@code{GNUNET_TESTBED_barrier_wait()}:} function to signal barrier | 1476 | @item @strong{@code{GNUNET_TESTBED_barrier_wait()}:} function to signal |
1402 | service that the caller has reached a barrier and is waiting for it to be | 1477 | barrier service that the caller has reached a barrier and is waiting for |
1403 | crossed | 1478 | it to be crossed |
1404 | @item @strong{@code{GNUNET_TESTBED_barrier_wait_cancel()}:} function to stop | 1479 | @item @strong{@code{GNUNET_TESTBED_barrier_wait_cancel()}:} function to |
1405 | waiting for a barrier to be crossed | 1480 | stop waiting for a barrier to be crossed |
1406 | @end itemize | 1481 | @end itemize |
1407 | 1482 | ||
1408 | 1483 | ||
1409 | Among the above functions, the first two, namely | 1484 | Among the above functions, the first two, namely |
1410 | @code{GNUNET_TESTBED_barrier_init()} and @code{GNUNET_TESTBED_barrier_cancel()} | 1485 | @code{GNUNET_TESTBED_barrier_init()} and |
1411 | are used by experiment drivers. All barriers should be initialised by the | 1486 | @code{GNUNET_TESTBED_barrier_cancel()} are used by experiment drivers. All |
1412 | experiment driver by calling @code{GNUNET_TESTBED_barrier_init()}. This | 1487 | barriers should be initialised by the experiment driver by calling |
1413 | function takes a name to identify the barrier, the quorum required for the | 1488 | @code{GNUNET_TESTBED_barrier_init()}. This function takes a name to |
1414 | barrier to be crossed and a notification callback for notifying the experiment | 1489 | identify the barrier, the quorum required for the barrier to be crossed |
1415 | driver when the barrier is crossed. @code{GNUNET_TESTBED_barrier_cancel()} | 1490 | and a notification callback for notifying the experiment driver when the |
1416 | cancels an initialised barrier and frees the resources allocated for it. This | 1491 | barrier is crossed. @code{GNUNET_TESTBED_barrier_cancel()} cancels an |
1492 | initialised barrier and frees the resources allocated for it. This | ||
1417 | function can be called upon a initialised barrier before it is crossed. | 1493 | function can be called upon a initialised barrier before it is crossed. |
1418 | 1494 | ||
1419 | The remaining two functions @code{GNUNET_TESTBED_barrier_wait()} and | 1495 | The remaining two functions @code{GNUNET_TESTBED_barrier_wait()} and |
1420 | @code{GNUNET_TESTBED_barrier_wait_cancel()} are used in the peer's processes. | 1496 | @code{GNUNET_TESTBED_barrier_wait_cancel()} are used in the peer's |
1421 | @code{GNUNET_TESTBED_barrier_wait()} connects to the local barrier service | 1497 | processes. @code{GNUNET_TESTBED_barrier_wait()} connects to the local |
1422 | running on the same host the peer is running on and registers that the caller | 1498 | barrier service running on the same host the peer is running on and |
1423 | has reached the barrier and is waiting for the barrier to be crossed. Note that | 1499 | registers that the caller has reached the barrier and is waiting for the |
1424 | this function can only be used by peers which are started by testbed as this | 1500 | barrier to be crossed. Note that this function can only be used by peers |
1425 | function tries to access the local barrier service which is part of the testbed | 1501 | which are started by testbed as this function tries to access the local |
1426 | controller service. Calling @code{GNUNET_TESTBED_barrier_wait()} on an | 1502 | barrier service which is part of the testbed controller service. Calling |
1427 | uninitialised barrier results in failure. | 1503 | @code{GNUNET_TESTBED_barrier_wait()} on an uninitialised barrier results |
1428 | @code{GNUNET_TESTBED_barrier_wait_cancel()} cancels the notification registered | 1504 | in failure. @code{GNUNET_TESTBED_barrier_wait_cancel()} cancels the |
1429 | by @code{GNUNET_TESTBED_barrier_wait()}. | 1505 | notification registered by @code{GNUNET_TESTBED_barrier_wait()}. |
1430 | 1506 | ||
1431 | 1507 | ||
1432 | @c *************************************************************************** | 1508 | @c *********************************************************************** |
1433 | @menu | 1509 | @menu |
1434 | * Implementation:: | 1510 | * Implementation:: |
1435 | @end menu | 1511 | @end menu |
@@ -1437,10 +1513,11 @@ by @code{GNUNET_TESTBED_barrier_wait()}. | |||
1437 | @node Implementation | 1513 | @node Implementation |
1438 | @subsubsection Implementation | 1514 | @subsubsection Implementation |
1439 | 1515 | ||
1440 | Since barriers involve coordination between experiment driver and peers, the | 1516 | Since barriers involve coordination between experiment driver and peers, |
1441 | barrier service in the testbed controller is split into two components. The | 1517 | the barrier service in the testbed controller is split into two |
1442 | first component responds to the message generated by the barrier API used by | 1518 | components. The first component responds to the message generated by the |
1443 | the experiment driver (functions @code{GNUNET_TESTBED_barrier_init()} and | 1519 | barrier API used by the experiment driver (functions |
1520 | @code{GNUNET_TESTBED_barrier_init()} and | ||
1444 | @code{GNUNET_TESTBED_barrier_cancel()}) and the second component to the | 1521 | @code{GNUNET_TESTBED_barrier_cancel()}) and the second component to the |
1445 | messages generated by barrier API used by peers (functions | 1522 | messages generated by barrier API used by peers (functions |
1446 | @code{GNUNET_TESTBED_barrier_wait()} and | 1523 | @code{GNUNET_TESTBED_barrier_wait()} and |
@@ -1449,11 +1526,11 @@ messages generated by barrier API used by peers (functions | |||
1449 | Calling @code{GNUNET_TESTBED_barrier_init()} sends a | 1526 | Calling @code{GNUNET_TESTBED_barrier_init()} sends a |
1450 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_INIT} message to the master | 1527 | @code{GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_INIT} message to the master |
1451 | controller. The master controller then registers a barrier and calls | 1528 | controller. The master controller then registers a barrier and calls |
1452 | @code{GNUNET_TESTBED_barrier_init()} for each its subcontrollers. In this way | 1529 | @code{GNUNET_TESTBED_barrier_init()} for each its subcontrollers. In this |
1453 | barrier initialisation is propagated to the controller hierarchy. While | 1530 | way barrier initialisation is propagated to the controller hierarchy. |
1454 | propagating initialisation, any errors at a subcontroller such as timeout | 1531 | While propagating initialisation, any errors at a subcontroller such as |
1455 | during further propagation are reported up the hierarchy back to the experiment | 1532 | timeout during further propagation are reported up the hierarchy back to |
1456 | driver. | 1533 | the experiment driver. |
1457 | 1534 | ||
1458 | Similar to @code{GNUNET_TESTBED_barrier_init()}, | 1535 | Similar to @code{GNUNET_TESTBED_barrier_init()}, |
1459 | @code{GNUNET_TESTBED_barrier_cancel()} propagates | 1536 | @code{GNUNET_TESTBED_barrier_cancel()} propagates |
@@ -1498,7 +1575,7 @@ propagation --- the upward propagation is needed for ensuring that the barrier | |||
1498 | is reached by all the controllers and the downward propagation is for | 1575 | is reached by all the controllers and the downward propagation is for |
1499 | triggering that the barrier is crossed. | 1576 | triggering that the barrier is crossed. |
1500 | 1577 | ||
1501 | @c *************************************************************************** | 1578 | @c *********************************************************************** |
1502 | @node Automatic large-scale deployment of GNUnet in the PlanetLab testbed | 1579 | @node Automatic large-scale deployment of GNUnet in the PlanetLab testbed |
1503 | @subsection Automatic large-scale deployment of GNUnet in the PlanetLab testbed | 1580 | @subsection Automatic large-scale deployment of GNUnet in the PlanetLab testbed |
1504 | 1581 | ||
@@ -1515,7 +1592,7 @@ Please also check @uref{https://gnunet.org/installation-fedora8-svn} and@ | |||
1515 | instructions how to install GNUnet on a PlanetLab node. | 1592 | instructions how to install GNUnet on a PlanetLab node. |
1516 | 1593 | ||
1517 | 1594 | ||
1518 | @c *************************************************************************** | 1595 | @c *********************************************************************** |
1519 | @menu | 1596 | @menu |
1520 | * PlanetLab Automation for Fedora8 nodes:: | 1597 | * PlanetLab Automation for Fedora8 nodes:: |
1521 | * Install buildslave on PlanetLab nodes running fedora core 8:: | 1598 | * Install buildslave on PlanetLab nodes running fedora core 8:: |
@@ -1526,7 +1603,7 @@ instructions how to install GNUnet on a PlanetLab node. | |||
1526 | @node PlanetLab Automation for Fedora8 nodes | 1603 | @node PlanetLab Automation for Fedora8 nodes |
1527 | @subsubsection PlanetLab Automation for Fedora8 nodes | 1604 | @subsubsection PlanetLab Automation for Fedora8 nodes |
1528 | 1605 | ||
1529 | @c *************************************************************************** | 1606 | @c *********************************************************************** |
1530 | @node Install buildslave on PlanetLab nodes running fedora core 8 | 1607 | @node Install buildslave on PlanetLab nodes running fedora core 8 |
1531 | @subsubsection Install buildslave on PlanetLab nodes running fedora core 8 | 1608 | @subsubsection Install buildslave on PlanetLab nodes running fedora core 8 |
1532 | @c ** Actually this is a subsubsubsection, but must be fixed differently | 1609 | @c ** Actually this is a subsubsubsection, but must be fixed differently |
@@ -1554,7 +1631,7 @@ The setup will download the matching twisted package and install it.@ It will | |||
1554 | also try to install the latest version of zope.interface which will fail to | 1631 | also try to install the latest version of zope.interface which will fail to |
1555 | install. Buildslave will work anyway since version 3.8.0 was installed before! | 1632 | install. Buildslave will work anyway since version 3.8.0 was installed before! |
1556 | 1633 | ||
1557 | @c *************************************************************************** | 1634 | @c *********************************************************************** |
1558 | @node Setup a new PlanetLab testbed using GPLMT | 1635 | @node Setup a new PlanetLab testbed using GPLMT |
1559 | @subsubsection Setup a new PlanetLab testbed using GPLMT | 1636 | @subsubsection Setup a new PlanetLab testbed using GPLMT |
1560 | 1637 | ||
@@ -1600,7 +1677,7 @@ Use @code{buildbot start <basedir>} to start the server | |||
1600 | @item Setup the buildslaves | 1677 | @item Setup the buildslaves |
1601 | @end itemize | 1678 | @end itemize |
1602 | 1679 | ||
1603 | @c *************************************************************************** | 1680 | @c *********************************************************************** |
1604 | @node Why do i get an ssh error when using the regex profiler? | 1681 | @node Why do i get an ssh error when using the regex profiler? |
1605 | @subsubsection Why do i get an ssh error when using the regex profiler? | 1682 | @subsubsection Why do i get an ssh error when using the regex profiler? |
1606 | 1683 | ||
@@ -1623,7 +1700,7 @@ You can test your setup by running `ssh 127.0.0.1` in a terminal and then in | |||
1623 | the opened session run it again. If you were not asked for a password on either | 1700 | the opened session run it again. If you were not asked for a password on either |
1624 | login, then you should be good to go. | 1701 | login, then you should be good to go. |
1625 | 1702 | ||
1626 | @c *************************************************************************** | 1703 | @c *********************************************************************** |
1627 | @node TESTBED Caveats | 1704 | @node TESTBED Caveats |
1628 | @subsection TESTBED Caveats | 1705 | @subsection TESTBED Caveats |
1629 | 1706 | ||
@@ -1631,7 +1708,7 @@ This section documents a few caveats when using the GNUnet testbed | |||
1631 | subsystem. | 1708 | subsystem. |
1632 | 1709 | ||
1633 | 1710 | ||
1634 | @c *************************************************************************** | 1711 | @c *********************************************************************** |
1635 | @menu | 1712 | @menu |
1636 | * CORE must be started:: | 1713 | * CORE must be started:: |
1637 | * ATS must want the connections:: | 1714 | * ATS must want the connections:: |
@@ -1650,7 +1727,7 @@ indirectly depends on CORE being started with FORCESTART will also do. This | |||
1650 | issue largely arises if users try to over-optimize by not starting any services | 1727 | issue largely arises if users try to over-optimize by not starting any services |
1651 | with FORCESTART. | 1728 | with FORCESTART. |
1652 | 1729 | ||
1653 | @c *************************************************************************** | 1730 | @c *********************************************************************** |
1654 | @node ATS must want the connections | 1731 | @node ATS must want the connections |
1655 | @subsubsection ATS must want the connections | 1732 | @subsubsection ATS must want the connections |
1656 | 1733 | ||
@@ -1666,7 +1743,7 @@ of connection failures (see '-e' option of gnunet-testbed-profiler). This issue | |||
1666 | largely arises for dense overlay topologies, especially if you try to create | 1743 | largely arises for dense overlay topologies, especially if you try to create |
1667 | cliques with more than 20 peers. | 1744 | cliques with more than 20 peers. |
1668 | 1745 | ||
1669 | @c *************************************************************************** | 1746 | @c *********************************************************************** |
1670 | @node libgnunetutil | 1747 | @node libgnunetutil |
1671 | @section libgnunetutil | 1748 | @section libgnunetutil |
1672 | 1749 | ||
@@ -1717,7 +1794,7 @@ porting of GNUnet easier. | |||
1717 | * The CONTAINER_MDLL API:: | 1794 | * The CONTAINER_MDLL API:: |
1718 | @end menu | 1795 | @end menu |
1719 | 1796 | ||
1720 | @c *************************************************************************** | 1797 | @c *********************************************************************** |
1721 | @node Logging | 1798 | @node Logging |
1722 | @subsection Logging | 1799 | @subsection Logging |
1723 | 1800 | ||
@@ -1877,7 +1954,7 @@ an error in definition formatting or an error in regular expression syntax, and | |||
1877 | will not report the failure in any way. | 1954 | will not report the failure in any way. |
1878 | 1955 | ||
1879 | 1956 | ||
1880 | @c *************************************************************************** | 1957 | @c *********************************************************************** |
1881 | @menu | 1958 | @menu |
1882 | * Examples:: | 1959 | * Examples:: |
1883 | * Log files:: | 1960 | * Log files:: |
@@ -1924,7 +2001,7 @@ limitation, on Windows, GNUNET_FORCE_LOGFILE @strong{MUST} be set in order to | |||
1924 | GNUNET_FORCE_LOG to work. | 2001 | GNUNET_FORCE_LOG to work. |
1925 | 2002 | ||
1926 | 2003 | ||
1927 | @c *************************************************************************** | 2004 | @c *********************************************************************** |
1928 | @node Log files | 2005 | @node Log files |
1929 | @subsubsection Log files | 2006 | @subsubsection Log files |
1930 | 2007 | ||
@@ -1962,7 +2039,7 @@ begins. If you do not use any date-related string format codes, logs would | |||
1962 | never be automatically deleted by GNUnet. | 2039 | never be automatically deleted by GNUnet. |
1963 | 2040 | ||
1964 | 2041 | ||
1965 | @c *************************************************************************** | 2042 | @c *********************************************************************** |
1966 | 2043 | ||
1967 | @node Updated behavior of GNUNET_log | 2044 | @node Updated behavior of GNUNET_log |
1968 | @subsubsection Updated behavior of GNUNET_log | 2045 | @subsubsection Updated behavior of GNUNET_log |
@@ -2032,7 +2109,7 @@ GNUNET_FORCE_LOG="^YOUR_SUBSYSTEM$;;;;DEBUG/;;;;WARNING"}@ Which will behave | |||
2032 | almost like enabling DEBUG in that subsytem before the change. Of course you | 2109 | almost like enabling DEBUG in that subsytem before the change. Of course you |
2033 | can adapt it to your particular needs, this is only a quick example. | 2110 | can adapt it to your particular needs, this is only a quick example. |
2034 | 2111 | ||
2035 | @c *************************************************************************** | 2112 | @c *********************************************************************** |
2036 | @node Interprocess communication API (IPC) | 2113 | @node Interprocess communication API (IPC) |
2037 | @subsection Interprocess communication API (IPC) | 2114 | @subsection Interprocess communication API (IPC) |
2038 | 2115 | ||
@@ -2045,7 +2122,7 @@ AddressLookupMessage} as a request to ask the server to return the address of | |||
2045 | any other peer connecting to the service.) | 2122 | any other peer connecting to the service.) |
2046 | 2123 | ||
2047 | 2124 | ||
2048 | @c *************************************************************************** | 2125 | @c *********************************************************************** |
2049 | @menu | 2126 | @menu |
2050 | * Define new message types:: | 2127 | * Define new message types:: |
2051 | * Define message struct:: | 2128 | * Define message struct:: |
@@ -2072,7 +2149,7 @@ First of all, you should define the new message type in | |||
2072 | #define GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY 30 | 2149 | #define GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_REPLY 30 |
2073 | @end example | 2150 | @end example |
2074 | 2151 | ||
2075 | @c *************************************************************************** | 2152 | @c *********************************************************************** |
2076 | @node Define message struct | 2153 | @node Define message struct |
2077 | @subsubsection Define message struct | 2154 | @subsubsection Define message struct |
2078 | 2155 | ||
@@ -2096,7 +2173,7 @@ both ensure correct alignment when sending structs over the network | |||
2096 | @menu | 2173 | @menu |
2097 | @end menu | 2174 | @end menu |
2098 | 2175 | ||
2099 | @c *************************************************************************** | 2176 | @c *********************************************************************** |
2100 | @node Client - Establish connection | 2177 | @node Client - Establish connection |
2101 | @subsubsection Client - Establish connection | 2178 | @subsubsection Client - Establish connection |
2102 | @c %**end of header | 2179 | @c %**end of header |
@@ -2110,7 +2187,7 @@ struct GNUNET_CLIENT_Connection *client; client = | |||
2110 | GNUNET_CLIENT_connect ("transport", cfg); | 2187 | GNUNET_CLIENT_connect ("transport", cfg); |
2111 | @end example | 2188 | @end example |
2112 | 2189 | ||
2113 | @c *************************************************************************** | 2190 | @c *********************************************************************** |
2114 | @node Client - Initialize request message | 2191 | @node Client - Initialize request message |
2115 | @subsubsection Client - Initialize request message | 2192 | @subsubsection Client - Initialize request message |
2116 | @c %**end of header | 2193 | @c %**end of header |
@@ -2135,7 +2212,7 @@ endian, about the usage of the big/small edian order and the corresponding | |||
2135 | conversion function please refer to Introduction of Big Endian and Little | 2212 | conversion function please refer to Introduction of Big Endian and Little |
2136 | Endian. | 2213 | Endian. |
2137 | 2214 | ||
2138 | @c *************************************************************************** | 2215 | @c *********************************************************************** |
2139 | @node Client - Send request and receive response | 2216 | @node Client - Send request and receive response |
2140 | @subsubsection Client - Send request and receive response | 2217 | @subsubsection Client - Send request and receive response |
2141 | @c %**end of header | 2218 | @c %**end of header |
@@ -2169,7 +2246,7 @@ argc, char**argv) @{ GNUNET_SERVICE_run(argc, argv, "transport" | |||
2169 | GNUNET_SERVICE_OPTION_NONE, &run, NULL)); @} | 2246 | GNUNET_SERVICE_OPTION_NONE, &run, NULL)); @} |
2170 | @end example | 2247 | @end example |
2171 | 2248 | ||
2172 | @c *************************************************************************** | 2249 | @c *********************************************************************** |
2173 | @node Server - Add new handles for specified messages | 2250 | @node Server - Add new handles for specified messages |
2174 | @subsubsection Server - Add new handles for specified messages | 2251 | @subsubsection Server - Add new handles for specified messages |
2175 | @c %**end of header | 2252 | @c %**end of header |
@@ -2207,7 +2284,7 @@ variable size, for special cases the exact size of the specified message also | |||
2207 | can be set. In addition, the terminator sign depicted as @code{@{NULL, NULL, 0, | 2284 | can be set. In addition, the terminator sign depicted as @code{@{NULL, NULL, 0, |
2208 | 0@}} is set in the last aera. | 2285 | 0@}} is set in the last aera. |
2209 | 2286 | ||
2210 | @c *************************************************************************** | 2287 | @c *********************************************************************** |
2211 | @node Server - Process request message | 2288 | @node Server - Process request message |
2212 | @subsubsection Server - Process request message | 2289 | @subsubsection Server - Process request message |
2213 | @c %**end of header | 2290 | @c %**end of header |
@@ -2248,7 +2325,7 @@ request message, and the processing of this request would be terminated. | |||
2248 | In comparison to the aforementioned situation, when the argument is equal to | 2325 | In comparison to the aforementioned situation, when the argument is equal to |
2249 | @code{GNUNET_OK}, the service would continue to process the requst message. | 2326 | @code{GNUNET_OK}, the service would continue to process the requst message. |
2250 | 2327 | ||
2251 | @c *************************************************************************** | 2328 | @c *********************************************************************** |
2252 | @node Server - Response to client | 2329 | @node Server - Response to client |
2253 | @subsubsection Server - Response to client | 2330 | @subsubsection Server - Response to client |
2254 | @c %**end of header | 2331 | @c %**end of header |
@@ -2278,7 +2355,7 @@ GNUNET_SERVER_transmit_context_run (tc, rtimeout); | |||
2278 | Note that, there are also a number of other APIs provided to the service to | 2355 | Note that, there are also a number of other APIs provided to the service to |
2279 | send the message. | 2356 | send the message. |
2280 | 2357 | ||
2281 | @c *************************************************************************** | 2358 | @c *********************************************************************** |
2282 | @node Server - Notification of clients | 2359 | @node Server - Notification of clients |
2283 | @subsubsection Server - Notification of clients | 2360 | @subsubsection Server - Notification of clients |
2284 | @c %**end of header | 2361 | @c %**end of header |
@@ -2302,7 +2379,7 @@ the server code still typically needs to call@ | |||
2302 | @code{GNUNET_SERVER_receive_done} so that the client can transmit further | 2379 | @code{GNUNET_SERVER_receive_done} so that the client can transmit further |
2303 | messages to the server. | 2380 | messages to the server. |
2304 | 2381 | ||
2305 | @c *************************************************************************** | 2382 | @c *********************************************************************** |
2306 | @node Conversion between Network Byte Order (Big Endian) and Host Byte Order | 2383 | @node Conversion between Network Byte Order (Big Endian) and Host Byte Order |
2307 | @subsubsection Conversion between Network Byte Order (Big Endian) and Host Byte Order | 2384 | @subsubsection Conversion between Network Byte Order (Big Endian) and Host Byte Order |
2308 | @c %** subsub? it's a referenced page on the ipc document. | 2385 | @c %** subsub? it's a referenced page on the ipc document. |
@@ -2357,7 +2434,7 @@ GNUNET_TIME_absolute_ntoh (struct GNUNET_TIME_AbsoluteNBO a) Convert relative | |||
2357 | time from network byte order. | 2434 | time from network byte order. |
2358 | @end table | 2435 | @end table |
2359 | 2436 | ||
2360 | @c *************************************************************************** | 2437 | @c *********************************************************************** |
2361 | 2438 | ||
2362 | @node Cryptography API | 2439 | @node Cryptography API |
2363 | @subsection Cryptography API | 2440 | @subsection Cryptography API |
@@ -2394,7 +2471,7 @@ used by most applications; most importantly,@ | |||
2394 | GNUNET_CRYPTO_rsa_key_create_from_hash does not create an RSA-key that should | 2471 | GNUNET_CRYPTO_rsa_key_create_from_hash does not create an RSA-key that should |
2395 | be considered secure for traditional applications of RSA. | 2472 | be considered secure for traditional applications of RSA. |
2396 | 2473 | ||
2397 | @c *************************************************************************** | 2474 | @c *********************************************************************** |
2398 | @node Message Queue API | 2475 | @node Message Queue API |
2399 | @subsection Message Queue API | 2476 | @subsection Message Queue API |
2400 | @c %**end of header | 2477 | @c %**end of header |
@@ -2518,7 +2595,7 @@ callback. When canceling an envelope, it is not necessary@ to call | |||
2518 | 2595 | ||
2519 | @strong{ Implementing Queues }@ @code{TODO} | 2596 | @strong{ Implementing Queues }@ @code{TODO} |
2520 | 2597 | ||
2521 | @c *************************************************************************** | 2598 | @c *********************************************************************** |
2522 | @node Service API | 2599 | @node Service API |
2523 | @subsection Service API | 2600 | @subsection Service API |
2524 | @c %**end of header | 2601 | @c %**end of header |
@@ -2584,7 +2661,7 @@ allowing existing 'normal' clients to set (possibly persistent) statistic | |||
2584 | values before terminating. | 2661 | values before terminating. |
2585 | @end table | 2662 | @end table |
2586 | 2663 | ||
2587 | @c *************************************************************************** | 2664 | @c *********************************************************************** |
2588 | @node Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps | 2665 | @node Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps |
2589 | @subsection Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps | 2666 | @subsection Optimizing Memory Consumption of GNUnet's (Multi-) Hash Maps |
2590 | @c %**end of header | 2667 | @c %**end of header |
@@ -2599,7 +2676,7 @@ API quirks (and their implications for applications) that were recently | |||
2599 | introduced to minimize the footprint of the hash map. | 2676 | introduced to minimize the footprint of the hash map. |
2600 | 2677 | ||
2601 | 2678 | ||
2602 | @c *************************************************************************** | 2679 | @c *********************************************************************** |
2603 | @menu | 2680 | @menu |
2604 | * Analysis:: | 2681 | * Analysis:: |
2605 | * Solution:: | 2682 | * Solution:: |
@@ -2652,7 +2729,7 @@ just an extreme example: overheads in practice are actually sometimes close to | |||
2652 | those highlighted in this example. This is especially true for maps with a | 2729 | those highlighted in this example. This is especially true for maps with a |
2653 | significant number of entries, as there we tend to really try to keep the | 2730 | significant number of entries, as there we tend to really try to keep the |
2654 | entries small. | 2731 | entries small. |
2655 | @c *************************************************************************** | 2732 | @c *********************************************************************** |
2656 | @node Solution | 2733 | @node Solution |
2657 | @subsubsection Solution | 2734 | @subsubsection Solution |
2658 | @c %**end of header | 2735 | @c %**end of header |
@@ -2668,7 +2745,7 @@ stores an entry in the hash map, it @strong{must} provide a pointer to the key | |||
2668 | within the entry, not just a pointer to a transient location of the key. If | 2745 | within the entry, not just a pointer to a transient location of the key. If |
2669 | the client code does not meet these requirements, the result is a dangling | 2746 | the client code does not meet these requirements, the result is a dangling |
2670 | pointer and undefined behavior of the (multi-)hash map API. | 2747 | pointer and undefined behavior of the (multi-)hash map API. |
2671 | @c *************************************************************************** | 2748 | @c *********************************************************************** |
2672 | @node Migration | 2749 | @node Migration |
2673 | @subsubsection Migration | 2750 | @subsubsection Migration |
2674 | @c %**end of header | 2751 | @c %**end of header |
@@ -2711,7 +2788,7 @@ If everything was done correctly, you now use about 60 bytes less memory per | |||
2711 | entry in @code{map}. However, if now (or in the future) any call to @code{put} | 2788 | entry in @code{map}. However, if now (or in the future) any call to @code{put} |
2712 | does not ensure that the given key is valid until the entry is removed from the | 2789 | does not ensure that the given key is valid until the entry is removed from the |
2713 | map, undefined behavior is likely to be observed. | 2790 | map, undefined behavior is likely to be observed. |
2714 | @c *************************************************************************** | 2791 | @c *********************************************************************** |
2715 | @node Conclusion | 2792 | @node Conclusion |
2716 | @subsubsection Conclusion | 2793 | @subsubsection Conclusion |
2717 | @c %**end of header | 2794 | @c %**end of header |
@@ -2722,7 +2799,7 @@ robust as additional invariants are imposed on the multi hash map client. Thus | |||
2722 | applications should refrain from enabling the new mode unless the resulting | 2799 | applications should refrain from enabling the new mode unless the resulting |
2723 | performance increase is deemed significant enough. In particular, it should | 2800 | performance increase is deemed significant enough. In particular, it should |
2724 | generally not be used in new code (wait at least until benchmarks exist). | 2801 | generally not be used in new code (wait at least until benchmarks exist). |
2725 | @c *************************************************************************** | 2802 | @c *********************************************************************** |
2726 | @node Availability | 2803 | @node Availability |
2727 | @subsubsection Availability | 2804 | @subsubsection Availability |
2728 | @c %**end of header | 2805 | @c %**end of header |
@@ -2733,7 +2810,7 @@ previously audited and modified to take advantage of the new capability. In | |||
2733 | particular, memory consumption of the file-sharing service is expected to drop | 2810 | particular, memory consumption of the file-sharing service is expected to drop |
2734 | by 20-30% due to this change. | 2811 | by 20-30% due to this change. |
2735 | 2812 | ||
2736 | @c *************************************************************************** | 2813 | @c *********************************************************************** |
2737 | @node The CONTAINER_MDLL API | 2814 | @node The CONTAINER_MDLL API |
2738 | @subsection The CONTAINER_MDLL API | 2815 | @subsection The CONTAINER_MDLL API |
2739 | @c %**end of header | 2816 | @c %**end of header |
@@ -2789,7 +2866,7 @@ functions for inserting (at head, at tail, after a given element) and removing | |||
2789 | elements from the list. Iterating over the list should be done by directly | 2866 | elements from the list. Iterating over the list should be done by directly |
2790 | accessing the "next_XX" and/or "prev_XX" members. | 2867 | accessing the "next_XX" and/or "prev_XX" members. |
2791 | 2868 | ||
2792 | @c *************************************************************************** | 2869 | @c *********************************************************************** |
2793 | @node The Automatic Restart Manager (ARM) | 2870 | @node The Automatic Restart Manager (ARM) |
2794 | @section The Automatic Restart Manager (ARM) | 2871 | @section The Automatic Restart Manager (ARM) |
2795 | @c %**end of header | 2872 | @c %**end of header |
@@ -2810,7 +2887,7 @@ with it. | |||
2810 | * Reliability:: | 2887 | * Reliability:: |
2811 | @end menu | 2888 | @end menu |
2812 | 2889 | ||
2813 | @c *************************************************************************** | 2890 | @c *********************************************************************** |
2814 | @node Basic functionality | 2891 | @node Basic functionality |
2815 | @subsection Basic functionality | 2892 | @subsection Basic functionality |
2816 | @c %**end of header | 2893 | @c %**end of header |
@@ -2833,7 +2910,7 @@ test_arm_api.c. The test case connects to ARM, starts it, then uses it to start | |||
2833 | a service "resolver", stops the "resolver" then stops "ARM". | 2910 | a service "resolver", stops the "resolver" then stops "ARM". |
2834 | @end itemize | 2911 | @end itemize |
2835 | 2912 | ||
2836 | @c *************************************************************************** | 2913 | @c *********************************************************************** |
2837 | @node Key configuration options | 2914 | @node Key configuration options |
2838 | @subsection Key configuration options | 2915 | @subsection Key configuration options |
2839 | @c %**end of header | 2916 | @c %**end of header |
@@ -2895,7 +2972,7 @@ that are going to run.@ | |||
2895 | 2972 | ||
2896 | @end table | 2973 | @end table |
2897 | 2974 | ||
2898 | @c *************************************************************************** | 2975 | @c *********************************************************************** |
2899 | @node Availability2 | 2976 | @node Availability2 |
2900 | @subsection Availability2 | 2977 | @subsection Availability2 |
2901 | @c %**end of header | 2978 | @c %**end of header |
@@ -2934,7 +3011,7 @@ work). | |||
2934 | @item Other client services now can directly connect directly to the "server". | 3011 | @item Other client services now can directly connect directly to the "server". |
2935 | @end itemize | 3012 | @end itemize |
2936 | 3013 | ||
2937 | @c *************************************************************************** | 3014 | @c *********************************************************************** |
2938 | @node Reliability | 3015 | @node Reliability |
2939 | @subsection Reliability | 3016 | @subsection Reliability |
2940 | 3017 | ||
@@ -2975,7 +3052,7 @@ backoff(S) will remain half an hour, hence ARM won't be busy for a lot of time | |||
2975 | trying to restart a problematic service. | 3052 | trying to restart a problematic service. |
2976 | @end itemize | 3053 | @end itemize |
2977 | 3054 | ||
2978 | @c *************************************************************************** | 3055 | @c *********************************************************************** |
2979 | @node GNUnet's TRANSPORT Subsystem | 3056 | @node GNUnet's TRANSPORT Subsystem |
2980 | @section GNUnet's TRANSPORT Subsystem | 3057 | @section GNUnet's TRANSPORT Subsystem |
2981 | @c %**end of header | 3058 | @c %**end of header |