Updated cache documentation

bqskit/runtime/__init__.py

@@ -166,30 +166,37 @@ def get_cache(self) -> dict[str, Any]:
         """
         Retrieve worker's local cache.
 
-        In situations where an large or non-easily serializable object is
+        In situations where a large or non-easily serializable object is
         needed during the execution of a custom pass, `get_cache` can be used
-        to load and store data. Objects placed in cache will last from when
-        they are  loaded until the end of a Compiler's Workflow execution.
-        Things placed  in cache are loaded once, then can be reused by
-        subsequent passes.
+        to load and store data. Objects placed in cache are transient. Objects
+        can be placed in cache to reduce reloading, but should not be expected
+        to remain in cache forever.
 
         For example, say some CustomPassA needs a SomeBigScaryObject. Within
         its run() method, the object is constructed, then placed into cache.
         A later pass, CustomPassB, also needs to use SomeBigScaryObject. It
         checks that the object has been loaded by CustomPassA, then uses it.
 
         ```
+            # Load helper method
+            def load_or_retrieve_big_scary_object(file):
+                worker_cache = get_runtime().get_cache()
+                if 'big_scary_object' not in worker_cache:
+                    # Expensive io operation...
+                    big_scary_object = load_big_scary_object(file)
+                    worker_cache['big_scary_object'] = big_scary_object
+                big_scary_object = worker_cache['big_scary_object']
+                return big_scary_object
+
             # In CustomPassA's .run() definition...
-            unpicklable_object = SomeBigScaryObject(...)
-            worker_cache = get_runtime().get_cache()
-            worker_cache['big_scary_object'] = unpicklable_object
-            unpicklable_object.use(...)
+            # CustomPassA performs the load.
+            big_scary_object = load_or_retrieve_big_scary_object(file)
+            big_scary_object.use(...)
 
             # In CustomPassB's .run() definition...
-            worker_cache = get_runtime().get_cache()
-            if 'big_scary_object' not in worker_cache:
-                raise RuntimeError('big_scary_object not found')
-            unpicklable_object = worker_cache['big_scary_object']
+            # CustomPassB saves time by retrieving big_scary_object from
+            # cache after CustomPassA has loaded it.
+            big_scary_object = load_or_retrieve_big_scary_object(file)
             unpicklable_object.use(...)
         ```
         """

bqskit/runtime/worker.py

@@ -576,8 +576,7 @@ def get_cache(self) -> dict[str, Any]:
                 worker process' memory. Passes on the same worker that use
                 the same object can load the object from this cache. If
                 there are multiple workers, those workers will load their
-                own copies of the object into their own cache. This happens
-                because all workers are assumed to be identical.
+                own copies of the object into their own cache.
         """
         return self._cache