diff options
-rw-r--r-- | doc/gnunet-c-tutorial.pdf | bin | 328988 -> 242423 bytes | |||
-rw-r--r-- | doc/gnunet-c-tutorial.tex | 122 |
2 files changed, 14 insertions, 108 deletions
diff --git a/doc/gnunet-c-tutorial.pdf b/doc/gnunet-c-tutorial.pdf index 5f3b21ca2..50dd98430 100644 --- a/doc/gnunet-c-tutorial.pdf +++ b/doc/gnunet-c-tutorial.pdf | |||
Binary files differ | |||
diff --git a/doc/gnunet-c-tutorial.tex b/doc/gnunet-c-tutorial.tex index 714333672..659b86980 100644 --- a/doc/gnunet-c-tutorial.tex +++ b/doc/gnunet-c-tutorial.tex | |||
@@ -375,12 +375,12 @@ Peer `9TVUCS8P5A7ILLBGO6JSTSSN2B44H3D2MUIFJMLKAITC0I22UVFBFP1H8NRK2IA35VKAK16LLO | |||
375 | GNUnet's testbed service is used for testing scenarios where a number of peers | 375 | GNUnet's testbed service is used for testing scenarios where a number of peers |
376 | are to be started. The testbed can manage peers on a single host or on multiple | 376 | are to be started. The testbed can manage peers on a single host or on multiple |
377 | hosts in a distributed fashion. On a single affordable computer, it should be | 377 | hosts in a distributed fashion. On a single affordable computer, it should be |
378 | possible to run around 100 peers without drastically increasing the load on the | 378 | possible to run around tens of peers without drastically increasing the load on the |
379 | system. | 379 | system. |
380 | 380 | ||
381 | The testbed service can be access through its API | 381 | The testbed service can be access through its API |
382 | \texttt{include/gnunet\_testbed\_service.h}. The API provides many routines for | 382 | \texttt{include/gnunet\_testbed\_service.h}. The API provides many routines for |
383 | managing a testbed. It also provides a helper function | 383 | managing a group of peers. It also provides a helper function |
384 | \texttt{GNUNET\_TESTBED\_test\_run()} to quickly setup a minimalistic testing | 384 | \texttt{GNUNET\_TESTBED\_test\_run()} to quickly setup a minimalistic testing |
385 | environment on a single host. | 385 | environment on a single host. |
386 | 386 | ||
@@ -392,116 +392,22 @@ and assigns the ports in configurations only if they are free. | |||
392 | 392 | ||
393 | Additionally, the testbed service also reads its options from the same | 393 | Additionally, the testbed service also reads its options from the same |
394 | configuration file. Various available options and details about them can be | 394 | configuration file. Various available options and details about them can be |
395 | found in the testbed default configuration file \texttt{testbed/testbed.conf}. | 395 | found in the testbed default configuration file \texttt{src/testbed/testbed.conf}. |
396 | 396 | ||
397 | With the testbed API, a sample test case can be structured as follows: | 397 | With the testbed API, a sample test case can be structured as follows: |
398 | \lstset{language=c} | 398 | \lstinputlisting[language=C]{testbed_test.c} |
399 | The source code for the above listing can be found at | ||
400 | \url{https://gnunet.org/svn/gnunet/doc/testbed_test.c}. After installing GNUnet, the above source code can be compiled as: | ||
401 | \lstset{language=bash} | ||
399 | \begin{lstlisting} | 402 | \begin{lstlisting} |
400 | /* Number of peers we want to start */ | 403 | $ export CPPFLAGS="-I/path/to/gnunet/headers" |
401 | #define NUM_PEERS 30 | 404 | $ export LDFLAGS="-L/path/to/gnunet/libraries" |
402 | 405 | $ gcc -o testbed-test -lgnunettestbed -lgnunetdht -lgnunetutil testbed_test.c | |
403 | struct GNUNET_TESTBED_Operation *dht_op; | ||
404 | |||
405 | struct GNUNET_DHT_Handle *dht_handle; | ||
406 | |||
407 | struct MyContext | ||
408 | { | ||
409 | int ht_len; | ||
410 | } ctxt; | ||
411 | |||
412 | static void finish () /* Finish test case */ | ||
413 | { | ||
414 | if (NULL != dht_op) | ||
415 | { | ||
416 | GNUNET_TESTBED_operation_done (dht_op); /* calls the dht_da() for closing | ||
417 | down the connection */ | ||
418 | dht_op = NULL; | ||
419 | } | ||
420 | result = GNUNET_OK; | ||
421 | GNUNET_SCHEDULER_shutdown (); /* Also kills the testbed */ | ||
422 | } | ||
423 | |||
424 | |||
425 | static void | ||
426 | service_connect_comp (void *cls, | ||
427 | struct GNUNET_TESTBED_Operation *op, | ||
428 | void *ca_result, | ||
429 | const char *emsg) | ||
430 | { | ||
431 | /* Service to DHT successful; do something */ | ||
432 | } | ||
433 | |||
434 | |||
435 | static void * | ||
436 | dht_ca (void *cls, const struct GNUNET_CONFIGURATION_Handle *cfg) | ||
437 | { | ||
438 | struct MyContext *ctxt = cls; | ||
439 | |||
440 | /* Use the provided configuration to connect to service */ | ||
441 | dht_handle = GNUNET_DHT_connect (cfg, ctxt->ht_len); | ||
442 | return dht_handle; | ||
443 | } | ||
444 | |||
445 | |||
446 | static void | ||
447 | dht_da (void *cls, void *op_result) | ||
448 | { | ||
449 | struct MyContext *ctxt = cls; | ||
450 | |||
451 | /* Disconnect from DHT service */ | ||
452 | GNUNET_DHT_disconnect ((struct GNUNET_DHT_Handle *) op_result); | ||
453 | ctxt->ht_len = 0; | ||
454 | dht_handle = NULL; | ||
455 | } | ||
456 | |||
457 | static void | ||
458 | test_master (void *cls, unsigned int num_peers, | ||
459 | struct GNUNET_TESTBED_Peer **peers) | ||
460 | { | ||
461 | /* Testbed is ready with peers running and connected in a pre-defined overlay | ||
462 | topology */ | ||
463 | |||
464 | /* do something */ | ||
465 | ctxt.ht_len = 10; | ||
466 | |||
467 | /* connect to a peers service */ | ||
468 | dht_op = GNUNET_TESTBED_service_connect | ||
469 | (NULL, /* Closure for operation */ | ||
470 | peers[0], /* The peer whose service to connect to */ | ||
471 | "dht" /* The name of the service */ | ||
472 | service_connect_comp, /* callback to call after a handle to service | ||
473 | is opened */ | ||
474 | NULL, /* closure for the above callback */ | ||
475 | dht_ca, /* callback to call with peer's configuration; | ||
476 | this should open the needed service connection */ | ||
477 | dht_da, /* callback to be called when closing the | ||
478 | opened service connection */ | ||
479 | &ctxt); /* closure for the above two callbacks */ | ||
480 | } | ||
481 | |||
482 | |||
483 | int | ||
484 | main (int argc, char **argv) | ||
485 | { | ||
486 | int ret; | ||
487 | |||
488 | ret = GNUNET_TESTBED_test_run | ||
489 | ("awesome-test", /* test case name */ | ||
490 | "template.conf", /* template configuration */ | ||
491 | NUM_PEERS, /* number of peers to start */ | ||
492 | 0LL, /* Event mask - set to 0 for no event notifications */ | ||
493 | NULL, /* Controller event callback */ | ||
494 | NULL, /* Closure for controller event callback */ | ||
495 | &test_master, /* continuation callback to be called when testbed setup is | ||
496 | complete */ | ||
497 | NULL); /* Closure for the test_master callback */ | ||
498 | if ( (GNUNET_OK != ret) || (GNUNET_OK != result) ) | ||
499 | return 1; | ||
500 | return 0; | ||
501 | } | ||
502 | \end{lstlisting} | 406 | \end{lstlisting} |
407 | The \texttt{CPPFLAGS} and \texttt{LDFLAGS} are necessary if GNUnet is installed | ||
408 | into a different directory other than \texttt{/usr/local}. | ||
503 | 409 | ||
504 | All of testbed API peer management functions treat management actions as | 410 | All of testbed API's peer management functions treat management actions as |
505 | operations and return operation handles. It is expected that the operations | 411 | operations and return operation handles. It is expected that the operations |
506 | begin immediately, but they may get delayed (to balance out load on the system). | 412 | begin immediately, but they may get delayed (to balance out load on the system). |
507 | The program using the API then has to take care of marking the operation as | 413 | The program using the API then has to take care of marking the operation as |
@@ -518,7 +424,7 @@ called. If the operation is not marked as done in that callback or if the | |||
518 | callback is given as NULL when creating the operation, the operation completion | 424 | callback is given as NULL when creating the operation, the operation completion |
519 | callback will be called. The API documentation shows which event are to be | 425 | callback will be called. The API documentation shows which event are to be |
520 | expected in the controller event notifications. It also documents any | 426 | expected in the controller event notifications. It also documents any |
521 | exceptional behaviours. | 427 | exceptional behaviour. |
522 | 428 | ||
523 | Once the peers are started, test cases often need to connect some of the peers' | 429 | Once the peers are started, test cases often need to connect some of the peers' |
524 | services. Normally, opening a connect to a peer's service requires the peer's | 430 | services. Normally, opening a connect to a peer's service requires the peer's |