[pypy-svn] r40058 - pypy/dist/pypy/doc

guido at codespeak.net guido at codespeak.net
Thu Mar 8 11:50:32 CET 2007


Author: guido
Date: Thu Mar  8 11:50:31 2007
New Revision: 40058

Modified:
   pypy/dist/pypy/doc/distribution.txt
Log:
Reformatting, rewording, typos.


Modified: pypy/dist/pypy/doc/distribution.txt
==============================================================================
--- pypy/dist/pypy/doc/distribution.txt	(original)
+++ pypy/dist/pypy/doc/distribution.txt	Thu Mar  8 11:50:31 2007
@@ -5,62 +5,62 @@
 
 Stuff & things. mostly
 
-Distributed library is an attempt to build a transparent, lazy
+The 'distributed' library is an attempt to provide transparent, lazy
 access to remote objects. This is accomplished using
-the `transparent proxy`_ approach and build on application
-level (pure python module).
+`transparent proxies`_ and in application level code (so as a pure
+python module).
 
-The main idea is to provide kind-of-RPC protocol, which
-accesses only necessary parts of objects (not whole objects)
-and also not to rely on objects being picklable nor having
-the same source code on both sides.
-
-In order to provide this, only necessary parts of remote objects
-are retrieved for every call, keeping remote references to objects
-which are not needed yet.
+The implementation uses an RPC-like protocol, which accesses
+only members of objects, rather than whole objects. This means it
+does not rely on objects being picklable, nor on having the same
+source code available on both sides. On each call, only the members
+that are used on the client side are retrieved, objects which
+are not used are merely references to their remote counterparts.
 
-Imagine remote object, which is locally available under name `x`.
-Let's call::
+As an example, let's imagine we have a remote object, locally available
+under the name `x`. Now we call::
 
     >>>> x.foo(1, [1,2,3], y)
 
-Where y is some instance of local, user-created class. So, what
-is really called, is a call to x.__getattribute__ with argument ('foo')
-which is copied, so remote side replies with a bound method. Locally
-this bound method appears as a remote reference which is again called
-with a remote reference to x as self, 1 (which is copied as a primitive type),
-reference to a list and refence to y. Remote side receives call to bound
-method x.foo, with x being resolved as local object, 1 as a immutable
-primitive, [1,2,3] as a reference to mutable primitive and y as a reference
-to remote object. If type of y is not known on remote side, the type of
-y is faked, given enough shape to be able to perform operations. The contents
-of a list are not retrieved as long as thei're not needed.
-
-This approach transfers minimal data over network, but tends to send
-tones of small packages to remote side. This might be improved at some
-point in future. Also this approach allows to have remote references to
-internal interpreter types, like frames, code objects and tracebacks. In
-a demo directory there is an example of using this to attach pdb.post\_mortem()
-to a remote traceback.
-
-Distributed lib is build with an abstract network layer, which means you
-can provide it any possible communication channel which can
-send/receive marshallable objects (no pickle needed!) via
-two functions - send and receive.
+where y is some instance of a local, user-created class.
+
+Under water, x.\_\_getattribute\_\_ is called, with argument 'foo'. In the
+\_\_getattribute\_\_ implementation, the 'foo' attribute is requested, and the
+remote side replies by providing a bound method. On the client this bound
+method appears as a remote reference: this reference is called with a remote
+reference to x as self, the integer 1 which is copied as a primitive type, a
+reference to a list and a refence to y. The remote side receives this call,
+processes it as a call to the bound method x.foo, where 'x' is resolved as a
+local object, 1 as an immutable primitive, [1,2,3] as a reference to a mutable
+primitive and y as a reference to a remote object. If the type of y is not
+known on the remote side, it is faked with just about enough shape (XXX?!?) to
+be able to perform the required operations.  The contents of the list are
+retrieved when they're needed.
+
+An advantage of this approach is that a user can have remote references to
+internal interpreter types, like frames, code objects and tracebacks. In a demo
+directory there is an example of using this to attach pdb.post\_mortem() to a
+remote traceback. Another advantage is that there's a minimal amount of data
+transferred over the network. On the other hand, there are a large amount of
+packages sent to the remote side - hopefully this will be improved in future.
+
+The 'distributed' lib is uses an abstract network layer, which means you
+can provide custom communication channels just by implementing
+two functions that send and receive marshallable objects (no pickle needed!).
 
 Exact rules of copying
 ----------------------
 
-- Immutable primitives are always transfered
+- Immutable primitives are always transferred
 
-- Mutable primitives are transfered as reference, but several operations
-  (like iter()) force them to appear
+- Mutable primitives are transferred as a reference, but several operations
+  (like iter()) force them to be transferred fully
 
-- Builtin exceptions are transfered by name
+- Builtin exceptions are transferred by name
 
 - User objects are always faked on the other side, with enough shape
-  transfered
+  transferred
 
 XXX finish, basic interface, example, build some stuff on top of greenlets
 
-.. _`transparent proxy`: objspace-proxies.html#tproxy
+.. _`transparent proxies`: objspace-proxies.html#tproxy



More information about the Pypy-commit mailing list