Add a note on using the `with` statement pattern.
@@ -579,7 +579,26 @@ class CompilerEnv(gym.Env):
"""Close the environment.
Once closed, :func:`reset` must be called before the environment is used
- again."""
+ again.
+
+ .. note::
+
+ Internally, CompilerGym environments may launch subprocesses and use
+ temporary files to communicate between the environment and the
+ underlying compiler (see :doc:`compiler_gym.service
+ <compiler_gym/service>` for details). This means it is important to
+ call :meth:`env.close() <compiler_gym.envs.CompilerEnv.close>` after
+ use to free up resources and prevent orphan subprocesses or files.
+ We recommend using the :code:`with` statement pattern for creating
+ environments:
+
+ >>> with gym.make("llvm-autophase-ic-v0") as env:
+ ... env.reset()
+ ... # use env how you like
+
+ This removes the need to call :meth:`env.close()
+ <compiler_gym.envs.CompilerEnv.close>` yourself.
+ """
# Try and close out the episode, but errors are okay.
close_service = True
if self.in_episode:
