:py:mod:`qsearch.checkpoints` ============================= .. py:module:: qsearch.checkpoints .. autoapi-nested-parse:: This module defines the Checkpoint class, which is used for storing intermediate state while compiling, to allow an interrupted compilation to resume at a later time. Two default implementations are provided. It is recommended that you look at FileCheckpoint as an example if you are interested in writing your own implementation. .. attribute:: FileCheckpoint Saves and recovers the intermediate state from a file, specified as "statefile" in the options. .. attribute:: ChildCheckpoint Allows for hierarchial checkpointing, which is useful in cases where there are sub-compilers, such as with LEAP. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: qsearch.checkpoints.Checkpoint qsearch.checkpoints.FileCheckpoint qsearch.checkpoints.ChildCheckpoint .. py:class:: Checkpoint(options=options.Options()) This class is used for storing intermediate state while compiling, to allow an interrupted compilation to resume at a later time. .. py:method:: save(self, state) :abstractmethod: Save the passed state to be recovered later. :param state: A Python object representing the intermediate state of the compilation. Usually a dictionary, but it could be anything. :type state: object .. py:method:: recover(self) :abstractmethod: Return the state previously stored with save(state). :returns: A Python object equivalent to the object originally stored via save(state), or None if no state is saved. :rtype: object .. py:method:: delete(self) :abstractmethod: Delete the state that was stored such that None will be returned next time recover() is called. .. py:class:: FileCheckpoint(options=options.Options()) Bases: :py:obj:`Checkpoint` This Checkpoint will store the state in the file specified in the options as statefile. Options: statefile : A string with a filepath where the state will be stored, or None, in which case no state will be stored and None will always be returned by recover() .. py:method:: save(self, state) Save the passed state to be recovered later. :param state: A Python object representing the intermediate state of the compilation. Usually a dictionary, but it could be anything. :type state: object .. py:method:: recover(self) Return the state previously stored with save(state). :returns: A Python object equivalent to the object originally stored via save(state), or None if no state is saved. :rtype: object .. py:method:: delete(self) Delete the state that was stored such that None will be returned next time recover() is called. .. py:class:: ChildCheckpoint(options=options.Options()) Bases: :py:obj:`Checkpoint` This Checkpoint is used for hierarchial checkpointing for when there is a sub-compiler, such as in LEAP. Options: parent (required) : The Checkpoint class that the creator of the ChildCheckpoint was passed. Below is an explanation of how ChildCheckpoint works. See leap_compiler for an example. My compiler class, ParentCompiler, is passed a FileCheckpoint as options.checkpoint. I create a ChildCheckpoint with the FileCheckpoint as the parent: child_checkpoint = ChildCheckpoint(Options(parent=options.checkpoint)) I pass this ChildCheckpoint to the sub-compiler I create: sub_compiler = SubCompiler(Options(checkpoint=child_checkpoint)) To the SubCompiler, the passed ChildCheckpoint will behave as any other Checkpoint would be expected to behavior, saving state with save(state), and recovering it with recover(), and deleting it with delete(). As the ParentCompiler, you save your state with save_parent(parentstate), recover it with recover_parent(), and deleting it with delete_parent(), making these function calls to child_checkpoint instead of interacting directly with the FileCheckpoint that was originally passed via options. The states of both ParentCompiler and SubCompiler will get saved in a manner specified by the original FileCheckpoint. ChildCheckpoint fully conforms to Checkpoint, and makes no assumptions about its parent, so it is compatible with any class that makes use ofa Checkpoint and works with any Checkpoint as a parent. This means you can even have multiple layers of nested ChildCheckpoint. However, the class creating the ChildCheckpoint must be sure to use the parent functions. Also, note that calling delete_parent() also deletes the state for the child. However, this is rather uncommon because usually it is the creator of the Checkpoint that calls delete, not the class it is passed to. For example, Project will call delete() to delete the checkpoint from a Compiler. ParentCompiler might call delete() to delete the state of SubCompiler once SubCompiler has finished (in fact, this happens in leap_compiler). .. py:method:: save(self, state) Save the passed state to be recovered later. :param state: A Python object representing the intermediate state of the compilation. Usually a dictionary, but it could be anything. :type state: object .. py:method:: save_parent(self, parentstate) Saves the parentstate alongside the child state. .. py:method:: recover(self) Return the state previously stored with save(state). :returns: A Python object equivalent to the object originally stored via save(state), or None if no state is saved. :rtype: object .. py:method:: recover_parent(self) Recovers the parentstate. .. py:method:: delete(self) Delete the state that was stored such that None will be returned next time recover() is called. .. py:method:: delete_parent(self) Deletes the state. Note that this delete both the parentstate and the child state.