Updated get_cache documentation

bqskit/runtime/__init__.py

@@ -166,9 +166,32 @@ def get_cache(self) -> dict[str, Any]:
         """
         Retrieve worker's local cache.
 
-        A worker's local cache is implemented as a dictionary. This function can
-        be used to check the presence of data, or to place data directly into, a
-        worker's local cache.
+        In situations where an 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.
+
+        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.
+
+        ```
+            # In CustomPassA's .run() definition...
+            unpicklable_object = SomeBigScaryObject(...)
+            worker_cache = get_runtime().get_cache()
+            worker_cache['big_scary_object'] = unpicklable_object
+            unpicklable_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']
+            unpicklable_object.use(...)
+        ```
         """
         ...
 

bqskit/runtime/worker.py

@@ -571,8 +571,13 @@ def get_cache(self) -> dict[str, Any]:
         Retrieve worker's local cache.
 
         Returns:
-            (dict[str, Any]): The worker's local cache implemented
-                with a dictionary.
+            (dict[str, Any]): The worker's local cache. This cache can be
+                used to store large or unserializable objects within a
+                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.
         """
         return self._cache