Serialization is the process in which complex objects are converted to simple data that can be used to reconstruct the original object. There are two forms of serialization used in RPyC: by value an by reference.
Brine
Brine is a fast and secure by-value serializer/deserializer of simple data types (ints, strings, floats, booleans, tuples, and tuples of the aforementioned). It can only be used to serialize simple, immutable python objects, and therefore it is secure by nature. Unlike pickle, for instance, brine cannot be exploited to importing arbitrary modules or instantiating arbitrary classes.
API:
- dump(obj) - serializes the given objects into a string of bytes
- load(data) - deserializes the given string into a live python object
- dumpable(obj) - a predicate indicating whether the given object can be serialized by brine, i.e., it is one of the supported simple data types.
Vinegar
Vinegar is a secure by-value serializer/deserializer of exceptions.
API:
- dump(typ, val, tb, **config) - dumps the given exception info (type, value, traceback), returns a simple object that can be brined
- load(val, **config) - loads the given dumped-exception info, returns an exception object that can be raised
Boxing
Boxing is a by-reference serialization/deserialization of all mutable or non-simple objects. Boxing creates a remote reference to the object, while unboxing such a remote reference creates a local proxy object, called netref, that delegates all local operations to the remote one. Instead of creating a by-value copy of the original object, boxing only passes a reference to it.
Netref Proxies
Netrefs, or network references, are object proxies to their corresponding remote object. The netref looks and behaves just as if it were really the remote object, by delegating all local operations to the remote object. Netref objects are synchronous, meaning, each operation blocks until the result is ready.
Async Proxies
You can use the rpyc.helpers.async factory to create an asynchronous netref proxies, called async proxies. These proxies behave just like normal netrefs, with the exception being that invoking them does not block. Instead, it returns a promise object called AsyncResult. This object will eventually hold the result of the call.
Timed Async Proxies
Using rpyc.helpers.timed, you can create async proxies with a timeout. If the result does not arrive within the given timeout, an exception will be raised.
AsyncResults
AsyncResults are the results of asynchronous operations.
API:
- wait() - waits for the result to arrive, or until the object becomes expired
- set_expiry(timeout) - sets the time-to-live (TTL) of the AsyncResult object. After 'timeout' seconds, the object will become expired
- add_callback(func) - adds a callback to be called when the result is ready
- ready - property indicating whether the result is ready
- error - property indicating whether the result is an exception (True) or a normal value (False)
- expired - property indicating whether the AsyncResult object has expired (did not receive the result in time)
- value - the value of the AsyncResult (will block if the result is not yet ready)
