[shpy-commit] r2820 - shpy/trunk/dist/shpy/net

[hpk@codespeak.net]

Author: hpk
Date: Sun Jan 18 15:17:00 2004
New Revision: 2820

Added:
   shpy/trunk/dist/shpy/net/README.txt
Log:
a conceptual README which explains how the network code
is supposed to be used. (not implemented yet). 



Added: shpy/trunk/dist/shpy/net/README.txt
==============================================================================
--- (empty file)
+++ shpy/trunk/dist/shpy/net/README.txt	Sun Jan 18 15:17:00 2004
@@ -0,0 +1,43 @@
+how remote execution is supposed to be used 
+-------------------------------------------
+
+- bootstrap: client initializes server loop
+  on the server (which needs to run a 'startserver.py'
+  process).  Note that both client and server run 
+  the same dispatch.SocketConnection thread, 
+  accepting incoming source code and offering
+  a remote invocation API. 
+
+- in order to remotely execute source code you call
+
+    exec_remote(source) 
+
+  on your connection. this will asynchronously execute 
+  the given source code on the other side. Note that there 
+  there is no return value, just as with the usual 
+  python 'exec' statement. exec_remote returns 
+  immediately and does not actually guarantee that 
+  your source code is executed on the other side. 
+
+  Note that all other API calls use this 
+  low level mechanism in order to implement 
+  control/synchronous mechanisms. 
+
+- in order to get a result a more higher level 
+  function can be invoked:
+
+      call_asynchronous(callback, func, *args, **kwargs)
+
+  will send the source code of 'func' and invoke 
+  it on the other side with the given arguments.
+  this will not return any value directly but instead
+  invoke the given callback with the result when and if
+  it arrives from the remote execution of 'func'. 
+
+      res = call_synchronous(func, *args, **kwargs)
+ 
+  this will only returns after it received a result. 
+
+# XXX concept for object references (the above API 
+  does not differentiate between pickleable/copyable values 
+  and remote objects.