Merge pull request #118 from stealthrocket/serialization-readme

Add section describing serialization and its quirks

Author: chriso

README.md

@@ -201,6 +201,28 @@ async def transform(msg):
     ...
 ```
 
+### Serialization
+
+Dispatch uses the [pickle] library to serialize coroutines.
+
+[pickle]: https://docs.python.org/3/library/pickle.html
+
+Serialization of coroutines is enabled by a CPython extension.
+
+The user must ensure that the contents of their stack frames are
+serializable. That is, users should avoid using variables inside
+coroutines that cannot be pickled.
+
+If a pickle error is encountered, serialization tracing can be enabled
+with the `DISPATCH_TRACE=1` environment variable to debug the issue. The
+stacks of coroutines and generators will be printed to stdout before
+the pickle library attempts serialization.
+
+For help with a serialization issues, please submit a [GitHub issue][issues].
+
+[issues]: https://github.com/stealthrocket/dispatch-py/issues
+
+
 ## Examples
 
 Check out the [examples](examples/) directory for code samples to help you get

src/dispatch/experimental/durable/function.py

@@ -14,7 +14,7 @@
 from . import frame as ext
 from .registry import RegisteredFunction, lookup_function, register_function
 
-TRACE = os.getenv("DURABLE_TRACE", False)
+TRACE = os.getenv("DISPATCH_TRACE", False)
 
 FRAME_CLEARED = 4
 
@@ -114,7 +114,7 @@ def __getstate__(self):
             ip, sp, stack = None, None, None
 
         if TRACE:
-            print(f"\n[DURABLE] Serializing {self}:")
+            print(f"\n[DISPATCH] Serializing {self}:")
             print(f"function = {rfn.fn.__qualname__} ({rfn.filename}:{rfn.lineno})")
             print(f"code hash = {rfn.hash}")
             print(f"args = {self.args}")