3.2 Profile-based compilation

This section lists the functions that use the Python profiler and line tracer to discover which functions it should compile. These routines are best to use if your application doesn't have a clear "slow spot" where a lot of time is spent algorithmically. If it does, the previous section is all you need.

In Python 2.1 the profiler hooks add a considerable overhead to Python's normal execution. This has been fixed in Python 2.2. The extra cost will easily overweight Psyco's benefits. The function background does not suffer from this (nor do the functions decribed in the other sections of this user guide).

With Python older than 2.2.2 the profiler will only collect data about the main thread in multi-threaded applications.

full( memory=None, time=None, memorymax=None, timemax=None)

Compile as much as possible.

Very efficient for small scripts and applications. Might be overkill for large applications: the memory blow-up and the time spent compiling a large amount of code could outweight the benefits.

With a Python older than 2.2.2, each function will only be compiled and run the second time it is entered. A function running a complex algorithm only once will sadly never be accelerated.

The (optional) arguments are described in the next sections.

profile( watermark=0.09, halflife=0.5, pollfreq=20, parentframe=0.25, memory=None, time=None, memorymax=None, timemax=None)

Do profiling to detect the functions that consume a lot of interpretation time, and only compile those.

As far as I can tell, the best solution for large applications. With Python 2.2.2, if a function takes a long time to run, it will be detected and compiled while it is still running, in the middle of its execution. Psyco takes it away from the standard interpreter.

The (optional) arguments are used for fine-tuning. They are described in the next sections.

background( watermark=0.09, halflife=0.5, pollfreq=100, parentframe=0.25, memory=None, time=None, memorymax=None, timemax=None)

This is similar to psyco.profile, but does not use active profiling. It only starts a background thread that periodically checks where the execution point is in all the other threads, and collects statistics based on this.

While quite less accurate, this method has the advantage of adding only a very small overhead to the standard execution and might be suited to large applications with an occasional algorithmically-intensive function.

The (optional) arguments are used for fine-tuning. They are described in the next sections. Try putting a "psyco.background()" call in your site.py file, with a larger watermark. Psyco will stay in the shadow and you should not notice it at all until you do some heavy work in Python. This feature may be less useful with Python older than 2.2.2, because Psyco cannot compile a function while it is running, but only the next time it is entered.

runonly( memory=None, time=None, memorymax=None, timemax=None): Run the compiled functions but don't compile new ones.
Python 2.2.2 only. The usefulness of this routine is unknown. See below.

stop( ): Stop the current profiler and purge the profiler queue (described below).
Calling this function prevents Psyco from compiling any new function. It will still execute the ones that have already been compiled.

cannotcompile( object): Prevents the given function to be ever compiled by Psyco. object can also be a method object or directly a code object. Raises psyco.error if the object is already being compiled. Note that this does not prevent functions called by object to be compiled, if the profilers want them to.

Note: most comments on the performance are based on small tests and extrapolations. Just don't trust what I guess and try yourself. Any comment about which routine you found most useful or what value you often give to parameters are welcome!

Subsections