From: Claudio-Daniel Freire <claudio-daniel.freire@inria.fr>
Date: Mon, 16 May 2011 14:36:21 +0000 (+0200)
Subject: Document stock implementation functions
X-Git-Tag: nepi_v2~33
X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=f334a92fc1b1ee96b50306fbf2c74798fe1e4a9e;p=nepi.git

Document stock implementation functions
---

diff --git a/src/nepi/util/tunchannel_impl.py b/src/nepi/util/tunchannel_impl.py
index 2b637f47..db22db66 100644
--- a/src/nepi/util/tunchannel_impl.py
+++ b/src/nepi/util/tunchannel_impl.py
@@ -205,6 +205,12 @@ class TunChannel(object):
 
 
 def create_tunchannel(testbed_instance, guid, devnull = []):
+    """
+    TunChannel factory for metadata.
+    By default, silences traceing.
+    
+    You can override the created element's attributes if you will.
+    """
     if not devnull:
         # just so it's not open if not needed
         devnull.append(open("/dev/null","w"))
@@ -212,26 +218,16 @@ def create_tunchannel(testbed_instance, guid, devnull = []):
     element.stderr = devnull[0] # silence tracing
     testbed_instance._elements[guid] = element
 
-def crossconnect_tunchannel_peer_init(proto, testbed_instance, tun_guid, peer_data):
-    tun = testbed_instance._elements[tun_guid]
-    tun.peer_addr = peer_data.get("tun_addr")
-    tun.peer_proto = peer_data.get("tun_proto") or proto
-    tun.peer_port = peer_data.get("tun_port")
-    tun.tun_key = min(tun.tun_key, peer_data.get("tun_key"))
-    tun.tun_proto = proto
+def preconfigure_tunchannel(testbed_instance, guid):
+    """
+    TunChannel preconfiguration.
     
-    preconfigure_tunchannel(testbed_instance, tun_guid)
-
-def crossconnect_tunchannel_peer_compl(proto, testbed_instance, tun_guid, peer_data):
-    # refresh (refreshable) attributes for second-phase
-    tun = testbed_instance._elements[tun_guid]
-    tun.peer_addr = peer_data.get("tun_addr")
-    tun.peer_proto = peer_data.get("tun_proto") or proto
-    tun.peer_port = peer_data.get("tun_port")
+    It initiates the forwarder thread for listening tcp channels.
     
-    postconfigure_tunchannel(testbed_instance, tun_guid)
-
-def preconfigure_tunchannel(testbed_instance, guid):
+    Takes the public address from the operating system, so it should be adequate
+    for most situations when the TunChannel forwarder thread runs in the same
+    process as the testbed controller.
+    """
     element = testbed_instance._elements[guid]
     
     # Find external interface, if any
@@ -262,13 +258,70 @@ def preconfigure_tunchannel(testbed_instance, guid):
         element.Prepare()
 
 def postconfigure_tunchannel(testbed_instance, guid):
+    """
+    TunChannel preconfiguration.
+    
+    Initiates the forwarder thread for connecting tcp channels or 
+    udp channels in general.
+    
+    Should be adequate for most implementations.
+    """
     element = testbed_instance._elements[guid]
     
     # Second-phase setup
     element.Setup()
+
+
+def crossconnect_tunchannel_peer_init(proto, testbed_instance, tun_guid, peer_data,
+        preconfigure_tunchannel = preconfigure_tunchannel):
+    """
+    Cross-connection initialization.
+    Should be adequate for most implementations.
+    
+    For use in metadata, bind the first "proto" argument with the connector type. Eg:
+    
+        conn_init = functools.partial(crossconnect_tunchannel_peer_init, "tcp")
+    
+    If you don't use the stock preconfigure function, specify your own as a keyword argument.
+    """
+    tun = testbed_instance._elements[tun_guid]
+    tun.peer_addr = peer_data.get("tun_addr")
+    tun.peer_proto = peer_data.get("tun_proto") or proto
+    tun.peer_port = peer_data.get("tun_port")
+    tun.tun_key = min(tun.tun_key, peer_data.get("tun_key"))
+    tun.tun_proto = proto
+    
+    preconfigure_tunchannel(testbed_instance, tun_guid)
+
+def crossconnect_tunchannel_peer_compl(proto, testbed_instance, tun_guid, peer_data,
+        postconfigure_tunchannel = postconfigure_tunchannel):
+    """
+    Cross-connection completion.
+    Should be adequeate for most implementations.
+    
+    For use in metadata, bind the first "proto" argument with the connector type. Eg:
+    
+        conn_init = functools.partial(crossconnect_tunchannel_peer_compl, "tcp")
+    
+    If you don't use the stock postconfigure function, specify your own as a keyword argument.
+    """
+    # refresh (refreshable) attributes for second-phase
+    tun = testbed_instance._elements[tun_guid]
+    tun.peer_addr = peer_data.get("tun_addr")
+    tun.peer_proto = peer_data.get("tun_proto") or proto
+    tun.peer_port = peer_data.get("tun_port")
+    
+    postconfigure_tunchannel(testbed_instance, tun_guid)
+
     
 
 def wait_tunchannel(testbed_instance, guid):
+    """
+    Wait for the channel forwarder to be up and running.
+    
+    Useful as a start function to assure proper startup synchronization,
+    be certain to start TunChannels before applications that might require them.
+    """
     element = testbed_instance.elements[guid]
     element.Wait()