CPU time

Satella’s cpu_time helps your processes play nice with the overall CPU usage, ie. deferring non-critical tasks to until CPU usage falls lower than the average.

cpu_time does this by periodically monitoring CPU’s usage and building your usage profile. The profile is refreshed each X minutes.

satella.instrumentation.cpu_time.calculate_occupancy_factor() → float

Get the average load between now and the time it was last called as a float, where 0.0 is LA=0 and 1.0 is LA=max_cores.

This will be the average between now and the time it was last called.


This in rare cases (being called the first or the second time) may block for up to 0.1 seconds

Returns:a float between 0 and 1 telling you how occupied CPU-wise is your system.
satella.instrumentation.cpu_time.sleep_cpu_aware(seconds: Union[str, float], of_below: Optional[float] = None, of_above: Optional[float] = None, check_each: float = 1) → bool

Sleep for specified number of seconds.

Quit earlier if the occupancy factor goes below of_below or above of_above :param seconds: time to sleep in seconds, or a time string :param of_below: occupancy factor below which the sleep will return :param of_above: occupancy factor above which the sleep will return :param check_each: amount of seconds to sleep at once :return: whether was awoken due to CPU time condition

Here’s the primary thread you can use to work with things:

class satella.instrumentation.cpu_time.CPUTimeManager
static percentile(percent: float) → float

Return given percentile of current CPU time’s profile :param percent: float between 0 and 1 :return: the value of the percentile

static set_window_size(window_size: float) → None

Set the time that should be observed in order to build an execution profile.

Parameters:window_size – time, in seconds

And here’s a helpful variant of satella.coding.concurrent.IntervalTerminableThread:

class satella.instrumentation.cpu_time.CPUTimeAwareIntervalTerminableThread(seconds: Union[str, float], max_sooner: Optional[float] = None, percentile: float = 0.3, wakeup_interval: Union[str, float] = '3s', *args, **kwargs)

An IntervalTerminableThread that can call the loop a bit faster than usual, based of current CPU time metrics.

  • seconds – time that a single looping through should take. This will include the time spent on calling .loop(), the rest of this time will be spent safe_sleep()ing. Can be alternatively a time string
  • max_sooner – amount of seconds that is ok to call this earlier. Default is 10% seconds.
  • percentile – percentile that CPU usage has to fall below to call it earlier.
  • wakeup_interval – amount of seconds to wake up between to check for _terminating status. Can be also a time string

Same concerns for terminate_on as in TerminableThread apply.

loop() → None

Override me!


Calls self.loop() indefinitely, until terminating condition is met