gnunet-svn
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[GNUnet-SVN] r1413 - GNUnet-docs/WWW


From: grothoff
Subject: [GNUnet-SVN] r1413 - GNUnet-docs/WWW
Date: Tue, 12 Jul 2005 11:45:06 -0700 (PDT)

Author: grothoff
Date: 2005-07-12 11:44:59 -0700 (Tue, 12 Jul 2005)
New Revision: 1413

Modified:
   GNUnet-docs/WWW/hacking.php3
   GNUnet-docs/WWW/hacking_application.php3
   GNUnet-docs/WWW/hacking_future.php3
   GNUnet-docs/WWW/hacking_organization.php3
   GNUnet-docs/WWW/hacking_rpc.php3
   GNUnet-docs/WWW/hacking_server.php3
   GNUnet-docs/WWW/hacking_testcases.php3
   GNUnet-docs/WWW/hacking_threading.php3
   GNUnet-docs/WWW/hacking_util.php3
Log:
docs

Modified: GNUnet-docs/WWW/hacking.php3
===================================================================
--- GNUnet-docs/WWW/hacking.php3        2005-07-12 17:17:14 UTC (rev 1412)
+++ GNUnet-docs/WWW/hacking.php3        2005-07-12 18:44:59 UTC (rev 1413)
@@ -11,7 +11,7 @@
 BP();
 W("This section is intented to be an introduction to programmers that want to 
extend the framework.");
 W("GNUnet has a layered design.");
-W("The basic goal for the layering is this:");
+W("An extremely high-level, simplified view is this:");
 EP();
 
 img("gnunet-design.png", "GNUnet layering", "CENTER", 401, 421, 0, 10, 10);
@@ -57,22 +57,36 @@
 DD("Keeping track of known peers, how much we trust them and what their 
current addresses are");
 DT("advertising");
 DD("Telling other peers about our addresses and forwarding advertisements");
+DT("bootstrap");
+DD("Using external means to learn about other peers to initially connect to 
the network (i.e. HTTP download of the hostlist)");
+DT("fragmentation");
+DD("Breaking of large (up to 64k) messages into smaller messages that fit the 
constraints of the MTU of the transport");
 DT("pingpong");
 DD("Sending PING messages to confirm that another peer is alive and 
notifications if other peers respond to our PINGs.");
 DT("session");
 DD("Establishing encrypted sessions with other peers");
+DT("topology");
+DD("Maintaining a diverse set of connections with other peers, that is 
deciding with which peers to establish connections at what time");
 DT("transport");
 DD("Hanlding of multiple low-level transports for direct communication with 
other peers (with UDP-like semantics)");
-DT("topology");
-DD("Maintaining a diverse set of connections with other peers, that is 
deciding with which peers to establish connections at what time");
-DT("bootstrap");
-DD("Using external means to learn about other peers to initially connect to 
the network (i.e. HTTP download of the hostlist)");
-DT("fragmentation");
-DD("Breaking of large (up to 64k) messages into smaller messages that fit the 
constraints of the MTU of the transport");
-DT("core");
-DD("Loading of modules, registering of handlers, event loops.");
 echo "</dl>";
 BP();
+DD("The core itself is responsible for loading of modules, registering of 
handlers and the event loops.");
+W("Various helper services exist for building applications.");
+W("The most important ones are:");
+EP();
+echo "<dl>";
+DT("getoption");
+DD("Allows clients (not other peers) to query the configuration of 
<tt>gnunetd</tt> via TCP.");
+DT("rpc");
+DD("Allows applications to make remote procedure calls, that is reliable 
invocations of functions with arguments and return values at another peer.");
+DT("stats");
+DD("Keeps statistics (pair of a string and an unsigned long long value) of 
arbitrary properties of GNUnet.  The service allows other modules to add new 
statistics, the application module allows <tt>gnunet-stats</tt> to query these 
values.");
+DT("traffic");
+DD("Keeps track of how many messages of which type were recently received or 
transmitted.  Can be queried by both other modules and by clients.  Used for 
example to ensure that enough cover traffic is available for anonymous 
operations where a high level of anonymity is desired.");
+echo "</dl>";
+BP();
+
 W("The following sections describe various aspects of the GNUnet code in more 
detail:");
 EP();
 include("hacking_index.inc");

Modified: GNUnet-docs/WWW/hacking_application.php3
===================================================================
--- GNUnet-docs/WWW/hacking_application.php3    2005-07-12 17:17:14 UTC (rev 
1412)
+++ GNUnet-docs/WWW/hacking_application.php3    2005-07-12 18:44:59 UTC (rev 
1413)
@@ -1,7 +1,7 @@
 <?php
 include("scripts.php3");
 $title = "GNUnet Documentation: writing applications";
-$description="GNUnet Documentation - a secure peer-to-peer framework starring 
anonymous file sharing with an excess based trust-economy";
+$description="How to write an application service for GNUnet";
 include("html_header.php3");
 
 H4("How do I write a new application service for GNUnet?");
@@ -17,11 +17,10 @@
 W("The first is a dynamic library that plugs into the GNUnet core.");
 W("This library must provide a single function which is invoked by the core 
when <tt>gnunetd</tt> starts.");
 W("This function registers a couple of callbacks with the GNUnet core in order 
to handle certain peer-to-peer messages.");
-W("Every peer-to-peer message is bounded in size (1300 octets) and must be 
bound to the appropriate application  module using a number typically defined 
in %s.",
-  extlink_("doxygen/html/gnunet__util_8h.html","src/include/gnunet_util.h"));
-W("The number must be globally unique.");
-W("The core module will be called whenever a peer-to-peer message matching a 
registered port number is received.");
-W("The core module can send messages to other nodes using the %s.",
+W("Every peer-to-peer message is bounded in size (about 60.000 octets) and 
must be bound to the appropriate application  module using a unique message 
identifier typically defined in %s.",
+  
extlink_("doxygen/html/gnunet__protocols_8h.html","src/include/gnunet_protocols.h"));
+W("The registered function of the application module will be called whenever a 
peer-to-peer message matching a registered message identifier is received.");
+W("The application module can send messages to other nodes using the %s.",
   
extlink_("doxygen/html/structCoreAPIForApplication.html","CoreAPIForApplication"));
 W("Typically, the module will also make use of GNUnet&rsquo;s client-server 
implementation %s to communicate with a user interface.",
   extlink_("doxygen/html/tcpserver_8c-source.html","tcpserver"));
@@ -35,7 +34,7 @@
   ARRAY(extlink_("doxygen/html/tcpio_8c.html","tcpio"),
        extlink_("doxygen/html/tcpserver_8c-source.html","tcpserver")));
 BR();
-W("The simplest way for a user interface to connect to the GNUnet core via TCP 
is to use the helper methods defined %s as part of the gnunet-util library; the 
library defines methods for %s and getting a client socket that is connected to 
<tt>gnunetd</tt>.",
+W("The simplest way for a user interface to connect to the GNUnet core via TCP 
is to use the helper methods defined %s as part of the <tt>gnunetutil</tt> 
library; the library defines methods for %s and getting a client socket that is 
connected to <tt>gnunetd</tt>.",
   ARRAY(extlink_("doxygen/html/port_8c-source.html","port.c"),
        extlink_("doxygen/html/printhelp_8c-source.html","parsing the command 
line options")));
 echo "</li></ol>";
@@ -47,32 +46,32 @@
 EP();
 echo "<ul>";
 echo "<li>";
-W("Avoid platform specific code outside src/util/");
+W("Avoid platform specific code outside of <tt>src/util/</tt>.");
 echo "</li>";
 echo "<li>";
-W("Do not use fork() or similar functions");
+W("Do not use <tt>fork()</tt> or similar functions.");
 echo "</li>";
 echo "<li>";
-W("Use gnunet_util_sleep() instead of sleep()");
+W("Use <tt>gnunet_util_sleep()</tt> instead of <tt>sleep()</tt>.");
 echo "</li>";
 echo "<li>";
-W("Use DIR_SEPARATOR and DIR_SEPARATOR_STR instead of plain slashes.");
+W("Use <tt>DIR_SEPARATOR</tt> and <tt>DIR_SEPARATOR_STR</tt> instead of plain 
slashes.");
 echo "</li>";
 echo "<li>";
-W("Use the uppercase macros defined in platform.h (CHDIR() instead of chdir(), 
CONNECT() instead of connect() etc.)");
+W("Use the uppercase macros defined in <tt>platform.h</tt> (for example, 
<tt>CHDIR()</tt> instead of <tt>chdir()</tt>, <tt>CONNECT()</tt> instead of 
<tt>connect()</tt>).");
 echo "</li>";
 echo "<li>";
-W("Use OPEN() instead of open()");
+W("Use <tt>fileopen()</tt> instead of <tt>open()</tt>");
 echo "</li>";
 echo "<li>";
 W("If an I/O function is missing in platform.h, ask the GNUnet developers.");
 W("The desired function may exist on all platforms, but its behavior may be 
different.");
 echo "</li>";
 echo "<li>";
-W("Always expect I/O operations to fail with EWOULDBLOCK, even if SELECT() 
returned the fd/socket.");
+W("Always expect I/O operations to fail with <tt>EWOULDBLOCK</tt>, even if 
<tt>SELECT()</tt> returned the descriptor as ready.");
 echo "</li>";
 echo "<li>";
-W("GTK functions may only be called from the main thread. Use gtkSaveCall().");
+W("GTK functions may only be called from the main thread.  Use 
<tt>gtkSaveCall()</tt> from the <tt>gnunetgtk_comon</tt> library before making 
any GTK calls.");
 echo "</li>";
 echo "</ul>";
 P();

Modified: GNUnet-docs/WWW/hacking_future.php3
===================================================================
--- GNUnet-docs/WWW/hacking_future.php3 2005-07-12 17:17:14 UTC (rev 1412)
+++ GNUnet-docs/WWW/hacking_future.php3 2005-07-12 18:44:59 UTC (rev 1413)
@@ -1,7 +1,7 @@
 <?php
 include("scripts.php3");
 $title = "GNUnet Documentation: Future Work";
-$description="GNUnet Documentation - a secure peer-to-peer framework starring 
anonymous file sharing with an excess based trust-economy";
+$description="Future work for GNUnet hackers";
 include("html_header.php3");
 
 ANCHOR("future");H3("Future Work");
@@ -18,18 +18,19 @@
 LI("more powerful user-interfaces (preferences, non-gtk+).");
 LI("write more extractors for %s (%s)",
    ARRAY(extlink_("/libextractor/","libextractor"),
-        extlink_("mailto:address@hidden","contact";)));
-LI("How about pseudonym based E-mail with accounting to fight Spam? E-mail 
without a central server at some ISP would also get rid of the pain with 
changing the address ever again.");
+        extlink_("mailto:address@hidden","contact";)));
 LI("fix %s",
    extlink_("https://gnunet.org/mantis/","bugs";));
-LI("port to OS X");
 LI("improve HTTP compatibility of HTTP transport service");
+LI("package binaries for various platforms");
+LI("design and implement a resillient, privacy-respecting chat protocol");
 echo "</ul>";
 BP();
 W("And if you want to go totally crazy:");
 EP();
 echo "<ul>";
 LI("distributed computation (sandboxing!?)");
+LI("How about pseudonym based E-mail with accounting to fight Spam? E-mail 
without a central server at some ISP would also get rid of the pain with 
changing the address ever again.");
 LI("add steganography to existing transport protocols");
 echo "</ul>";
 include("html_footer.php3");

Modified: GNUnet-docs/WWW/hacking_organization.php3
===================================================================
--- GNUnet-docs/WWW/hacking_organization.php3   2005-07-12 17:17:14 UTC (rev 
1412)
+++ GNUnet-docs/WWW/hacking_organization.php3   2005-07-12 18:44:59 UTC (rev 
1413)
@@ -10,30 +10,31 @@
 W("GNUnet is divided into several libraries.");
 W("Some libraries are statically linked (rare), some are shared libraries and 
many are plugins into the GNUnet core.");
 P();
-W("Static libraries are used for more internal re-use of code.");
-W("For example, the static gnunet-core library is used by the GNUnet deaemon 
and by various testcases and diagnostic tools.");
+W("Static libraries are used for purely internal re-use of code (not used at 
this point).");
 P();
 W("Shared libraries are used whenever multiple tools share code.");
-W("The general OS abstraction library, gnunet-util as well as libraries like 
libgnunet-ecrs that are used by multiple user interfaces belong into this 
category.");
+W("The general OS abstraction library, <tt>gnunetutil</tt> as well as 
libraries like <tt>libgnunetecrs</tt> that are used by multiple user interfaces 
belong into this category.");
 P();
-W("Finally, plugins are used for all of the code that is dynamically loaded by 
the gnunet daemon when needed.");
-W("This keeps the code for gnunetd small and modular.");
-W("Modules fall into two subcategories, services and applications.");
-W("Services are useless by themselves and only provide functionality for 
applications.");
-W("A simple example for a service is message fragmentation, which is a module 
that breaks larger messages into smaller messages and re-assembles them at the 
destination.");
+W("Finally, plugins are used for all of the code that is dynamically loaded by 
the gnunet daemon (or <tt>gnunet-gtk</tt>) when needed.");
+W("This keeps the code for <tt>gnunetd</tt> small and modular.");
+W("Modules fall into four subcategories, transport-services, internal 
services, application services and finally plugins for <tt>gnunet-gtk</tt>.");
+W("Internal services are useless by themselves and only provide functionality 
for application services.");
+W("A simple example for an internal service is message fragmentation, which is 
a module that breaks larger messages into smaller messages and re-assembles 
them at the destination.");
 W("Some services are required by the GNUnet core, others are purely 
optional.");
 W("By convention, the names for header files for service plugins end in 
<tt>_service.h</tt>.");
 W("Application modules provide useful services that are exposed to the user 
via user interfaces.");
-W("Examples for application modules are the file-sharing or the chat 
application modules.");
+W("Examples for application modules are the fs (file-sharing), tbench, 
tracekit and the chat application modules.");
 W("Application modules typically also provide one or more shared libraries to 
make it easier to write user interfaces for these applications.");
 W("By convention, the names of the header files for these convenience 
libraries end in <tt>_lib.h</tt>.");
-W("Note that the application modules themselves do not define a header file 
since they are accessed using a set of client-server messages exchanged using 
code from gnunet-util and the GNUnet core.");
+W("An example for such a convenience library is <tt>libgnunetfs</tt> with the 
header file <tt>gnunet_fs_lib.h</tt>.");
+W("In this case, the immediate API exposed by the fs application is extremely 
low-level and additional libraries (ECRS and FSUI) are used to provide 
higher-level abstractions.");
+W("Note that the application services themselves do not define a header file 
since they are accessed using a set of client-server messages exchanged using 
code from <tt>gnunetutil</tt> and the GNUnet core.");
 EP();
 
 ANCHOR("overview");H3("Important header files and libraries");
 
 BP();
-W("The most important modules in GNUnet are:");
+W("The most important header files in GNUnet are:");
 EP();
 echo "<ul>\n";
 LI(extlink_("#protocols","gnunet_protocols.h"));
@@ -54,8 +55,7 @@
 ANCHOR("transport");H4("gnunet_transport.h");
 BP();
 W("This header primarily defines the functions that any GNUnet transport 
service must implement.");
-W("The semantic of the transport service are essentially those of UDP:");
-W("out-of-order, unreliable, unencrypted delivery of bounded-size messages.");
+W("The semantic of the transport service are essentially those of UDP: 
out-of-order, unreliable, unencrypted delivery of bounded-size messages.");
 W("Each transport type can also define its own addressing scheme.");
 EP();
 ANCHOR("core");H4("gnunet_core.h");
@@ -75,8 +75,10 @@
   ARRAY(extlink_("doxygen/html/gnunetsearch_8c.html","gnunet-search"),
        extlink_("doxygen/html/gnunetinsert_8c.html","gnunet-insert"),
        extlink_("doxygen/html/tcpserver_8c.html","tcpserver")));
-W("A common request is a %s which is handed by the TCPSERVER in the GNUnet 
CORE to the FS service, which then passes the query to the %s for routing.",
+W("The actuall connection operation is initiated in some helper library 
written for the specific application, in this case <tt>libgnunetfsui</tt> calls 
<tt>libgnunetecrs</tt> which calls <tt>libgnunetfs</tt> which sends the actual 
request via TCP using <tt>libgnunetutil</tt>.");
+W("A common request is a %s which is handed by the %s in the GNUnet CORE to 
the FS service, which then passes the query to the internal %s for routing.",
   ARRAY(extlink_("doxygen/html/structTCP__Query__Request.html","query"),
+        extlink_("doxygen/html/tcpserver_8c.html","tcpserver"),
        extlink_("doxygen/html/gnunet__gap__service_8h.html","GAP service")));
 W("The GAP service then produces a query which is enqueued in the %s module of 
the CORE for transmission to other peers.",
   extlink_("#connection","connection"));

Modified: GNUnet-docs/WWW/hacking_rpc.php3
===================================================================
--- GNUnet-docs/WWW/hacking_rpc.php3    2005-07-12 17:17:14 UTC (rev 1412)
+++ GNUnet-docs/WWW/hacking_rpc.php3    2005-07-12 18:44:59 UTC (rev 1413)
@@ -1,7 +1,7 @@
 <?php
 include("scripts.php3");
-$title="GNUnet Documentation";
-$description="GNUnet Documentation - Using GNUnet RPC";
+$title="GNUnet Documentation: Remote Procedure Calls (RPC)";
+$description="Documentation of the GNUnet Remote Procedure Call Service (RPC)";
 include("html_header.php3");
 
 H2("The GNUnet RPC service");

Modified: GNUnet-docs/WWW/hacking_server.php3
===================================================================
--- GNUnet-docs/WWW/hacking_server.php3 2005-07-12 17:17:14 UTC (rev 1412)
+++ GNUnet-docs/WWW/hacking_server.php3 2005-07-12 18:44:59 UTC (rev 1413)
@@ -1,37 +1,35 @@
 <?php
 include("scripts.php3");
 $title = "GNUnet Documentation: Hacking gnunetd";
-$description="GNUnet Documentation - a secure peer-to-peer framework starring 
anonymous file sharing with an excess based trust-economy";
+$description="Description of the internals of the gnunetd process";
 include("html_header.php3");
 
 H2("Understanding gnunetd");
-P();
 
+BP();
+
 W("In GNUnet, the server <tt>gnunetd</tt> is responsible for loading modules, 
demultiplexing messages from clients and other peers and queueing (encrypted) 
messages for other peers.");
 W("The core also performs bandwidth allocation and scheduling.");
 W("The core relies on implementations of the %s for the actual transport of 
packets.",
-  extlink_("doxygen/html/structTransportAPI.html","TransportAPI"));
+  extlink_("doxygen/html/structTransportAPI.html",
+           "TransportAPI"));
 W("The transport layer has, like the internet protocol (IP) and UDP, 
best-effort semantics.");
 W("There is no guarantee that a message will be delivered.");
 BR();
-W("Applications (like file-sharing) are build on top of GNUnet.");
+W("Applications (like file-sharing) are build on top of the GNUnet core; the 
core itself has no notion of file-sharing.");
 W("Applications may consist of multiple services and use the %s to access the 
GNUnet core.",
-  
extlink_("doxygen/html/structCoreAPIForApplication.html","CoreAPIForApplication"));
+  extlink_("doxygen/html/structCoreAPIForApplication.html",
+           "CoreAPIForApplication"));
 W("If necessary, applications are responsible for adding reliability (through 
retransmission) to the networking layer.");
 W("A common way to do this is by using the RPC service.");
 W("The applications are also responsible for avoiding congestion (see TCP).");
 W("While the core will enforce bandwidth limitations set by the user, services 
should implement better strategies.");
 W("Applications communicate these strategies to the core by giving their 
message a priority and a desired time for transmission.");
 W("The core then considers the available bandwidth, deadlines and priorities, 
solves the resulting knapsack problem and schedules the messages.");
-W("The following picture shows that the knapsack solver actually works to 
reduce noise.");
-W("It was obtained by first runnung GNUnet with very high CPU load (knapsack 
disabled).");
-W("Once the CPU load dropped the knapsack solver went into action and reduced 
the amount of noise.");
-IMG("knapsack_works.png", "Traffic percentages with and without knapsack", 
"CENTER", 653, 841);
-
 BR();
 W("In order to ease the implementation, GNUnet splits applications in two main 
parts.");
 W("The first part resides in the process space of <tt>gnunetd</tt>.");
-W("This part is implemented as a plugin.");
+W("This part is implemented as an application plugin and possibly additional 
service plugins.");
 W("The core will notify this lowest layer of the service of messages that have 
arrived for the service.");
 W("This layer of the application is responsible for all node-to-node 
interactions.");
 W("Typically, the layer consists of multiple service modules.");
@@ -47,6 +45,8 @@
   extlink_("doxygen/html/tcpio_8c-source.html","tcpio"));
 W("Note that the TCP connection between the application and <tt>gnunetd</tt> 
is presumed to be totally secure (i.e. via loopback).");
 W("You can specify the list of trusted IP addresses (i.e. the LAN) that are 
allowed to connect as clients to GNUnetd.");
+EP();
 
+
 include("html_footer.php3");
 ?>

Modified: GNUnet-docs/WWW/hacking_testcases.php3
===================================================================
--- GNUnet-docs/WWW/hacking_testcases.php3      2005-07-12 17:17:14 UTC (rev 
1412)
+++ GNUnet-docs/WWW/hacking_testcases.php3      2005-07-12 18:44:59 UTC (rev 
1413)
@@ -1,7 +1,7 @@
 <?php
 include("scripts.php3");
 $title = "GNUnet Documentation: writing testcases";
-$description="GNUnet Documentation - how to write testcases for GNUnet";
+$description="How to write testcases for GNUnet";
 include("html_header.php3");
 
 H2("Writing testcases for GNUnet");
@@ -55,28 +55,11 @@
 W("The following code illustrates spawning and killing a <tt>gnunetd</tt> 
process from a testcase:");
 EP();
 PRE("pid_t daemon; \n" .
-    "daemon = fork();\n" .
-    "if (daemon == 0) {\n" .
-    "  if (0 != execlp(\"gnunetd\",\n" .
-    "                 \"gnunetd\",\n" .
-    "                 \"-d\",\n" .
-    "                 \"-c\", \"check.conf\",\n" .
-    "                 NULL)) {\n" .
-    "    fprintf(stderr,\n" .
-    "            _(\"'%s' failed: %s\\n\"),\n" .
-    "            \"execlp\",\n" .
-    "            STRERROR(errno));\n" .
-    "    return -1;\n" . 
-    "  }\n" .
-    "}\n" .
+    "daemon = startGNUnetDaemon(NO);\n" .
     "/* put actual testcode here */\n" .
     "if (daemon != -1) {\n" .
-    "  if (0 != kill(daemon, SIGTERM))\n" .
+    "  if (! termProcess(daemon))\n" .
     "    DIE_STRERROR(\"kill\");\n" .
-    "  if (daemon != waitpid(daemon, &status, 0))\n" .
-    "    DIE_STRERROR(\"waitpid\");\n" .
-    "  if (WEXITSTATUS(status) == 0)\n" .
-    "    return -1; /* server had error */\n" .
     "}\n");
 BP();
 W("An alternative way to just test modules (in particular if there is no 
client API to start with) is to implement a mock-version of the GNUnet core API 
and emulate a <tt>gnunetd</tt> environment for the module.");
@@ -91,4 +74,3 @@
 
 include("html_footer.php3");
 ?>
-

Modified: GNUnet-docs/WWW/hacking_threading.php3
===================================================================
--- GNUnet-docs/WWW/hacking_threading.php3      2005-07-12 17:17:14 UTC (rev 
1412)
+++ GNUnet-docs/WWW/hacking_threading.php3      2005-07-12 18:44:59 UTC (rev 
1413)
@@ -1,7 +1,7 @@
 <?php
 include("scripts.php3");
-$title = "GNUnet Documentation: Copyright and Philosophy";
-$description="GNUnet Documentation - a secure peer-to-peer framework starring 
anonymous file sharing with an excess based trust-economy";
+$title = "GNUnet Documentation: Threading in gnunetd";
+$description="This page describes the various threads that exist in gnunetd, 
how to use them and common pitfalls that should be avoided";
 include("html_header.php3");
 
 H4("Threading and Synchronization");
@@ -16,7 +16,7 @@
 W("The core may call registered callback handlers at any time, and also 
concurrently.");
 W("The application modules are responsible for synchronizing access to their 
internal state properly.");
 echo "</strong>";
-W("In practice, client code will use MUTEX_CREATE in initializers and then 
guard access to mutable global shared state using MUTEX_LOCK and 
MUTEX_UNLOCK.");
+W("In practice, client code will use <tt>MUTEX_CREATE</tt> in initializers and 
then guard access to mutable global shared state using <tt>MUTEX_LOCK</tt> and 
<tt>MUTEX_UNLOCK</tt>.");
 echo "</li><li><strong>";
 W("In order to avoid deadlocks, code that was called via callback from the 
core may not invoke methods on the core while holding locks of the 
application.");
 echo "</strong>";
@@ -26,7 +26,7 @@
 BR();BR();
 W("Programming with this paradigm is not very difficult.");
 W("Still, it often requires a simple trick if the callback to the core 
requires an argument that is typically kept in the shared global state.");
-W("The trick is, to copy the shared global state into a local buffer while 
holding the lock, then releasing the lock and finally doing the callback on the 
core.");
+W("The trick is to copy the shared global state into a local buffer while 
holding the lock, then releasing the lock and finally doing the callback on the 
core.");
 W("An example for this behavior can be found in the %s code.",
   extlink_("doxygen/html/querymanager_8c-source.html","querymanager"));
 W("Alternatively, the global lock from the connection module can be used to 
lock on the application specific state; this global lock may be held while 
entering the GNUnet kernel.");
@@ -47,15 +47,16 @@
 W("Thus the gnunetd %s code blocks on writes to the client.",
   extlink_("doxygen/html/cron_8c-source.html","tcpio"));
 W("Similarly, the client blocks when sending messages to gnunetd.");
-W("Since the client-server TCP connection is supposed to use a fast (loopback, 
LAN) connection and since gnunetd uses a thread per client connection, blocking 
on this connection is acceptable.");
-W("The problem with blocking here is that it leaves the possibility of an 
<em>inter-process deadlock</em>.");
+W("Since the client-server TCP connection is supposed to use a fast (loopback, 
LAN) connection and since <tt>gnunetd</tt> uses a thread per client connection, 
blocking briefly due to network latency on this connection is considered 
acceptable.");
+W("However, a common problem with blocking on TCP connections with clients is 
that it leaves the possibility of an <em>inter-process deadlock</em>.");
 BR();BR();
 W("The deadlock can occur if the TCP thread that receives and processes 
messages from the client blocks on a write to the client (TCP buffer queue 
full) and thus gnunetd no longer reads from the TCP pipe.");
-W("If the client blocks on a write to gnunetd and thus no longer reads from 
its end of the TCP connection, both processes block forever. This problem is 
typically hard to diagnose since it involves two processes and may only occur 
after the TCP buffers of the operating system are full.");
+W("If the client blocks on a write to <tt>gnunetd</tt> and thus no longer 
reads from its end of the TCP connection, both processes block forever.");
+W("This problem is typically hard to diagnose since it involves two processes 
and may only occur after the TCP buffers of the operating system are full.");
 W("A typical symptom is that <tt>netstat -tn</tt> shows two local TCP 
connections with very full receive and send buffers that do not change.");
 BR();BR();
-W("The solution to the problem is that every client (not peer, remember that 
clients are trusted and can thus be expected to follow the protocol correctly) 
must always be in a state where it has a thread that can receive and process 
messages from gnunetd.");
-W("That thread should never block, neither by doing a direct write to gnunetd 
nor by aquireing a lock that could be hold by another thread while that thread 
writes to gnunetd.");
+W("The solution to the problem is that every client (not peer, remember that 
clients are trusted and can thus be expected to follow the protocol correctly) 
must always be in a state where it has a thread that can receive and process 
messages from <tt>gnunetd</tt>.");
+W("That thread should never block, neither by doing a direct write to 
<tt>gnunetd</tt> nor by aquireing a lock that could be hold by another thread 
while that thread writes to <tt>gnunetd</tt>.");
 W("A typical solution to this problem is to use one thread that processes 
replies and another thread that generates requests.");
 W("Another solution is to use the non-blocking TCPIO call in the client.");
 W("The %s code is an example for code that handles this type of problem.",
@@ -64,9 +65,9 @@
 
 H5("Notes");
 echo "<ul><li>";
-W("You should never use pthread_detach.");
+W("You should never use <tt>pthread_detach</tt>.");
 W("There is hardly ever a good reason for it, and it can be the source of 
subtle bugs.");
-W("Write a shutdown-sequence for your code and make sure to use pthread_join 
on all created threads.");
+W("Write a shutdown-sequence for your code and make sure to use 
<tt>pthread_join</tt> on all created threads.");
 echo "</li></ul>";
 include("html_footer.php3");
 ?>
\ No newline at end of file

Modified: GNUnet-docs/WWW/hacking_util.php3
===================================================================
--- GNUnet-docs/WWW/hacking_util.php3   2005-07-12 17:17:14 UTC (rev 1412)
+++ GNUnet-docs/WWW/hacking_util.php3   2005-07-12 18:44:59 UTC (rev 1413)
@@ -1,75 +1,90 @@
 <?php
 include("scripts.php3");
-$title="GNUnet Documentation";
-$description="GNUnet Documentation - libgnunet_util";
+$title="GNUnet Documentation - libgnunetutil";
+$description="Programmer documentation for libgnunetutil";
 include("html_header.php3");
 
-H2("libgnunet_util");
+H2("libgnunetutil");
 BP();
 
-W("<tt>libgnunet_util</tt> is a helper library that is supposed to contain all 
platform dependent code (except for user interfaces).");
+W("<tt>libgnunetutil</tt> is a helper library that is supposed to contain all 
platform dependent code (except for user interfaces).");
 W("It is also supposed to offer basic services that most if not all GNUnet 
binaries require.");
-W("The code of <tt>libgnunet_util</tt> is in the <tt>src/util/</tt> 
directory.");
+W("The code of <tt>libgnunetutil</tt> is in the <tt>src/util/</tt> 
directory.");
 W("The public interface to the library is in the %s header.",
   extlink_("doxygen/html/gnunet__util_8h.html",
            "gnunet_util.h"));
-W("The functions provided by <tt>libgnunet_util</tt> fall roughly into the 
following categories:");
+W("The functions provided by <tt>libgnunetutil</tt> fall roughly into the 
following categories:");
 EP();
 ?>
 <ul>
+ <li><?php extlink("doxygen/html/logging_8c.html",
+                   "logging");?></li>
+
+ <li><?php extlink("doxygen/html/dso_8c.html",
+                   "plugin support (dynamically shared objects)");?></li>
+
  <li><?php extlink("doxygen/html/timer_8c.html",
                    "timing");?></li>
+ <li><?php extlink("doxygen/html/statuscalls_8c.html",
+                   "load management (network, CPU)");?></li>
+
  <li><?php extlink("doxygen/html/semaphore_8c.html",
                    "threading and synchronization");?></li>
- <li><?php extlink("doxygen/html/configuration_8c.html",
-                   "configuration");?></li>
- <li><?php extlink("doxygen/html/storage_8c.html",
-                   "IO");?></li>
- <li><?php extlink("doxygen/html/logging_8c.html",
-                   "logging");?></li>
+ <li><?php extlink("doxygen/html/cron_8c.html",
+                   "periodic or deferred tasks (cron jobs)");?></li>
+ <li><?php extlink("doxygen/html/shutdown_8c.html",
+                   "signal handling");?></li>
+
  <li><?php extlink("doxygen/html/tcpio_8c.html",
                    "Reliable (TCP), record-based client-server 
communication");?></li>
+ <li><?php extlink("doxygen/html/port_8c.html",
+                   "Connecting clients with <tt>gnunetd</tt>");?></li>
+ <li><?php extlink("doxygen/html/daemon_8c.html",
+                   "External process control of <tt>gnunetd</tt> by 
clients");?></li>
+
+ <li><?php extlink("doxygen/html/random_8c.html",
+                   "random number generation");?></li>
  <li><?php extlink("doxygen/html/hashing_8c.html",
                    "hashing");?></li>
  <li><?php extlink("doxygen/html/symcipher__gcry_8c.html",
                    "symmetric encryption");?></li>
  <li><?php extlink("doxygen/html/hostkey__gcry_8c.html",
                    "asymmetric encryption");?></li>
+
  <li><?php extlink("doxygen/html/xmalloc_8c.html",
                    "memory management");?></li>
- <li><?php extlink("doxygen/html/dso_8c.html",
-                   "plugin support (dynamically shared objects)");?></li>
- <li><?php extlink("doxygen/html/cron_8c.html",
-                   "periodic or deferred tasks (cron jobs)");?></li>
+ <li><?php extlink("doxygen/html/configuration_8c.html",
+                   "configuration");?></li>
+ <li><?php extlink("doxygen/html/storage_8c.html",
+                   "IO");?></li>
  <li><?php extlink("doxygen/html/state_8c.html",
                    "persistent storage, trivial string-based database");?></li>
- <li><?php extlink("doxygen/html/statistics_8c.html",
-                   "statistics; support for gnunet-stats");?></li>
  <li><?php extlink("doxygen/html/bloomfilter_8c.html",
                    "bloomfilter implementation (with on-disk bit 
counters)");?></li>
+
 </ul>
 <?php
 
-
 BP();
-W("Ideally, porting GNUnet should only require porting the gnunet_util 
library.");
-W("More testcases for the gnunet-util APIs are therefore a great way to make 
porting of GNUnet easier.");
+W("Ideally, porting GNUnet should only require porting the <tt>gnunetutil</tt> 
library.");
+W("More testcases for the <tt>gnunetutil</tt> APIs are therefore a great way 
to make porting of GNUnet easier.");
 EP();
 
 ANCHOR("crypto");
 H3("Cryptography");
 
 BP();
-W("The gnunet-util APIs also provide the cryptographic primitives used in 
GNUnet.");
+W("The <tt>gnunetutil</tt> APIs provides the cryptographic primitives used in 
GNUnet.");
 W("GNUnet uses 2048 bit RSA keys for the session key exchange and for signing 
messages by peers.");
 W("Most researchers in cryptography consider 2048 bit RSA keys as very secure 
and practically unbreakable for a very long time unless extraordinary advances 
in cryptography are made.");
-W("For the encryption of the files and the symmetric peer-to-peer 
communication GNUnet uses 128 bit keys with blowfish.");
-W("Fresh session keys are negotiated for every new connection.");
+W("For the encryption of the files and the symmetric peer-to-peer 
communication GNUnet uses 256-bit AES encryption.");
+W("Fresh, asymmetric session keys are negotiated for every new connection.");
 W("Again, there is no published technique to break this cipher in any 
realistic amount of time.");
+W("GNUnet uses SHA-512 for computing one-way hash codes.");
 W("Note that GNUnet does not use RSA to encrypt files or ordinary individual 
peer-to-peer messages.");
 W("No sane protocol uses public key cryptography for the bulk of the messages 
since public key encryption is extremely expensive compared to symmetric 
ciphers.");
 W("GNUnet follows the well-established practice to use public key cryptography 
to exchange an initial pair of symmetric keys that is then used for the rest of 
the communication).");
 EP();
 
 include("html_footer.php3");
-?>
\ No newline at end of file
+?>





reply via email to

[Prev in Thread] Current Thread [Next in Thread]