<OPTIMIZE> Directives

reStructuredPython allows you to apply runtime optimizations using special compiler directives and decorators. These directives can be applied to both loops and functions to enhance performance, enable diagnostics, and optionally parallelize execution.

Loop Optimization

Use <OPTIMIZE ...> before a for or while loop to apply runtime enhancements:

<OPTIMIZE gct=True, parallel=True, profile=True, cache=True> for i in range(10_000_000) {

temp = str(i) * 10

}

Added in version Added: the cache option in 2.6.0

Changed in version Changed: the parallel functionality in 2.6.0

Arguments for <OPTIMIZE …> on loops include:

  • gct=False: Trigger garbage collection before loop execution.

  • profile=False: Log execution time of the loop.

  • parallel=Flase: Attempts multithreading using concurrent.futures.ThreadPoolExecutor

  • cache=False: Enable memoization for loop-returning functions.

  • unroll=N: Unrolls loops to preserve preformance

Warning

<OPTIMIZE parallel=True> on loops uses multithreading only. For true multiprocessing, use python’s multiprocessing module with top-level functions and ensure your script includes freeze_support due to limitations of python’s multiprocessing setup.

Function Optimization

You can also apply <OPTIMIZE ...> before a function definition to enable diagnostics and performance enhancements:

<OPTIMIZE profile=True, trace=True, cache=True>
def compute(x) {
   return x ** 2
}

Arguments for <OPTIMIZE …> on functions include

  • cache=False: Uses LRU cahching for function memoization

  • profile=False: Log execution time of the function.

  • trace=True: Trace events for the function

This will generate a python file that imports the optimization decorators from this ( the restructuredpython package ), so you will need to have this package installed via pip on systems running your compiled, optimized program.

Note

However, as of 2.6.0, you could technically open the generated python file, remove the imports from restructuredpython, and instead use include 'subinterpreter.optimize'. However, this is expictily NOT recommended as it will break in future versions of reStructuredPython and will include an annoying copyright header in the generated file.

Note

We recommend running this with repycl the restructuredpython interpreter & launcher.