Design: States of OpenCLGA

We could know more details of OpenCLGA through its states. The following diagram is the states of OpenCL GA. It has 10 states. Each of them has its owned transitions:

1. Waiting: The waiting state is the first state of OpenCLGA. When we create the OpenCLGA, it is under this state. In waiting state, we can call two APIs, prepare or restore, to enter either preparing or restoring state. Please note they are exclusive.

2. Preparing: The preparing state is to run the GA from zero. It creates all memory objects among python and OpenCL devices. Once ready, it goes to prepared state. In this state, we cannot call any APIs. OpenCLGA just ignores all API calls.

3. Restoring: The restoring state is to run the GA from previous state. It loads memory objects from pickled object and restore all of them back to python and OpenCL devices. Once ready, it goes to prepared state. Same here, we cannot call any APIs in this state.

4. Prepared: The prepared state means everything is initialized and ready to go. We can use run API to kick off OpenCLGA.

5. Running: When OpenCLGA in running state, it goes into a busy loop to populate each generations. During execution, some callback functions are called. We can obtain best, avg, or worst result through those callbacks. If we want to pause or stop the executing, we can use another thread to call pause or stop API to do so. Once it finished one generation, OpenCLGA pauses or stops the execution.

6. Pausing: When pause API is called, OpenCLGA goes into this state. It waits until OpenCLGA finished one generation. Once finished, the state goes paused.

7. Paused: We can use get_the_best, get_statistics, save, and run API during this state. The former two APIs dumps the best information at that moment. The save API triggers the saving procedure of OpenCLGA to dump memory objects from python and OpenCL devices. If we calls run API at this state, OpenCLGA resumes the executing from the current memory objects. It is really useful if we want to see the result at the end of each generation.

8. Saving: The saving state dumps memory objects from python and OpenCL devices. The length of time in this state depends on how many memories OpenCLGA needs to dump. Once saved, the state goes back to paused.

9. Stopping: The stopping state tries to wait for the end of the current generation and copies the best result from OpenCL devices. Once finished, it goes to stopped state.

10. Stopped: The stopped state is the last state of OpenCLGA. We cannot execute the OpenCLGA anymore once it goes to this state. But we can still read the result through get_the_best and get_statistics APIs.