## statprof.py

## Copyright (C) 2012 Bryan O'Sullivan <bos@serpentine.com>

## Copyright (C) 2011 Alex Fraser <alex at phatcore dot com>

## Copyright (C) 2004,2005 Andy Wingo <wingo at pobox dot com>

## Copyright (C) 2001 Rob Browning <rlb at defaultvalue dot org>

## This library is free software; you can redistribute it and/or

## modify it under the terms of the GNU Lesser General Public

## License as published by the Free Software Foundation; either

## version 2.1 of the License, or (at your option) any later version.

##

## This library is distributed in the hope that it will be useful,

## but WITHOUT ANY WARRANTY; without even the implied warranty of

## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

## Lesser General Public License for more details.

##

## You should have received a copy of the GNU Lesser General Public

## License along with this program; if not, contact:

##

## Free Software Foundation           Voice:  +1-617-542-5942

## 59 Temple Place - Suite 330        Fax:    +1-617-542-2652

## Boston, MA  02111-1307,  USA       gnu@gnu.org

"""

statprof is intended to be a fairly simple statistical profiler for

python. It was ported directly from a statistical profiler for guile,

also named statprof, available from guile-lib [0].

[0] http://wingolog.org/software/guile-lib/statprof/

To start profiling, call statprof.start():

>>> start()

Then run whatever it is that you want to profile, for example:

>>> import test.pystone; test.pystone.pystones()

Then stop the profiling and print out the results:

>>> stop()

>>> display()

  %   cumulative      self

 time    seconds   seconds  name

 26.72      1.40      0.37  pystone.py:79:Proc0

 13.79      0.56      0.19  pystone.py:133:Proc1

 13.79      0.19      0.19  pystone.py:208:Proc8

 10.34      0.16      0.14  pystone.py:229:Func2

  6.90      0.10      0.10  pystone.py:45:__init__

  4.31      0.16      0.06  pystone.py:53:copy

    ...

All of the numerical data is statistically approximate. In the

following column descriptions, and in all of statprof, "time" refers

to execution time (both user and system), not wall clock time.

% time

    The percent of the time spent inside the procedure itself (not

    counting children).

cumulative seconds

    The total number of seconds spent in the procedure, including

    children.

self seconds

    The total number of seconds spent in the procedure itself (not

    counting children).

name

    The name of the procedure.

By default statprof keeps the data collected from previous runs. If you

want to clear the collected data, call reset():

>>> reset()

reset() can also be used to change the sampling frequency from the

default of 1000 Hz. For example, to tell statprof to sample 50 times a

second:

>>> reset(50)

This means that statprof will sample the call stack after every 1/50 of

a second of user + system time spent running on behalf of the python

process. When your process is idle (for example, blocking in a read(),

as is the case at the listener), the clock does not advance. For this

reason statprof is not currently not suitable for profiling io-bound

operations.

The profiler uses the hash of the code object itself to identify the

procedures, so it won't confuse different procedures with the same name.

They will show up as two different rows in the output.

Right now the profiler is quite simplistic.  I cannot provide

call-graphs or other higher level information.  What you see in the

table is pretty much all there is. Patches are welcome :-)

Threading

---------

Because signals only get delivered to the main thread in Python,

statprof only profiles the main thread. However because the time

reporting function uses per-process timers, the results can be

significantly off if other threads' work patterns are not similar to the

main thread's work patterns.

"""

# no-check-code

from __future__ import annotations

import collections

import contextlib

import getopt

import inspect

import json

import os

import signal

import sys

import threading

import time

from typing import (

    List,

)

from . import (

    encoding,

    pycompat,

)

defaultdict = collections.defaultdict

contextmanager = contextlib.contextmanager

__all__ = ['start', 'stop', 'reset', 'display', 'profile']

skips = {

    "util.py:check",

    "extensions.py:closure",

    "color.py:colorcmd",

    "dispatch.py:checkargs",

    "dispatch.py:<lambda>",

    "dispatch.py:_runcatch",

    "dispatch.py:_dispatch",

    "dispatch.py:_runcommand",

    "pager.py:pagecmd",

    "dispatch.py:run",

    "dispatch.py:dispatch",

    "dispatch.py:runcommand",

    "hg.py:<module>",

    "evolve.py:warnobserrors",

}

###########################################################################

## Utils

def clock():

    times = os.times()

    return (times[0] + times[1], times[4])

###########################################################################

## Collection data structures

class ProfileState:

    samples: List[Sample]

    def __init__(self, frequency=None):

        self.reset(frequency)

        self.track = b'cpu'

    def reset(self, frequency=None):

        # total so far

        self.accumulated_time = (0.0, 0.0)

        # start_time when timer is active

        self.last_start_time = None

        # a float

        if frequency:

            self.sample_interval = 1.0 / frequency

        elif not hasattr(self, 'sample_interval'):

            # default to 1000 Hz

            self.sample_interval = 1.0 / 1000.0

        else:

            # leave the frequency as it was

            pass

        self.remaining_prof_time = None

        # for user start/stop nesting

        self.profile_level = 0

        self.samples = []

    def accumulate_time(self, stop_time):

        increment = (

            stop_time[0] - self.last_start_time[0],

            stop_time[1] - self.last_start_time[1],

        )

        self.accumulated_time = (

            self.accumulated_time[0] + increment[0],

            self.accumulated_time[1] + increment[1],

        )

    def seconds_per_sample(self):

        return self.accumulated_time[self.timeidx] / len(self.samples)

    @property

    def timeidx(self):

        if self.track == b'real':

            return 1

        return 0

state = ProfileState()

class CodeSite:

    cache = {}

    __slots__ = ('path', 'lineno', 'function', 'source')

    def __init__(self, path, lineno, function):

        assert isinstance(path, bytes)

        self.path = path

        self.lineno = lineno

        assert isinstance(function, bytes)

        self.function = function

        self.source = None

    def __eq__(self, other):

        try:

            return self.lineno == other.lineno and self.path == other.path

        except:

            return False

    def __hash__(self):

        return hash((self.lineno, self.path))

    @classmethod

    def get(cls, path, lineno, function):

        k = (path, lineno)

        try:

            return cls.cache[k]

        except KeyError:

            v = cls(path, lineno, function)

            cls.cache[k] = v

            return v

    def getsource(self, length):

        if self.source is None:

            try:

                lineno = self.lineno - 1  # lineno can be None

                with open(self.path, 'rb') as fp:

                    for i, line in enumerate(fp):

                        if i == lineno:

                            self.source = line.strip()

                            break

            except:

                pass

            if self.source is None:

                self.source = b''

        source = self.source

        if len(source) > length:

            source = source[: (length - 3)] + b"..."

        return source

    def filename(self):

        return os.path.basename(self.path)

    def skipname(self):

        return '%s:%s' % (self.filename(), self.function)

class Sample:

    __slots__ = ('stack', 'time')

    def __init__(self, stack, time):

        self.stack = stack

        self.time = time

    @classmethod

    def from_frame(cls, frame, time):

        stack = []

        while frame:

            stack.append(

                CodeSite.get(

                    pycompat.sysbytes(frame.f_code.co_filename),

                    frame.f_lineno,

                    pycompat.sysbytes(frame.f_code.co_name),

                )

            )

            frame = frame.f_back

        return Sample(stack, time)

###########################################################################

## SIGPROF handler

def profile_signal_handler(signum, frame):

    if state.profile_level > 0:

        now = clock()

        state.accumulate_time(now)

        timestamp = state.accumulated_time[state.timeidx]

        state.samples.append(Sample.from_frame(frame, timestamp))

        signal.setitimer(signal.ITIMER_PROF, state.sample_interval, 0.0)

        state.last_start_time = now

stopthread = threading.Event()

def samplerthread(tid):

    while not stopthread.is_set():

        now = clock()

        state.accumulate_time(now)

        frame = sys._current_frames()[tid]

        timestamp = state.accumulated_time[state.timeidx]

        state.samples.append(Sample.from_frame(frame, timestamp))

        state.last_start_time = now

        time.sleep(state.sample_interval)

    stopthread.clear()

###########################################################################

## Profiling API

def is_active():

    return state.profile_level > 0

lastmechanism = None

def start(mechanism=b'thread', track=b'cpu'):

    '''Install the profiling signal handler, and start profiling.'''

    state.track = track  # note: nesting different mode won't work

    state.profile_level += 1

    if state.profile_level == 1:

        state.last_start_time = clock()

        rpt = state.remaining_prof_time

        state.remaining_prof_time = None

        global lastmechanism

        lastmechanism = mechanism

        if mechanism == b'signal':

            signal.signal(signal.SIGPROF, profile_signal_handler)

            signal.setitimer(

                signal.ITIMER_PROF, rpt or state.sample_interval, 0.0

            )

        elif mechanism == b'thread':

            frame = inspect.currentframe()

            tid = [k for k, f in sys._current_frames().items() if f == frame][0]

            state.thread = threading.Thread(

                target=samplerthread, args=(tid,), name="samplerthread"

            )

            state.thread.start()

def stop():

    '''Stop profiling, and uninstall the profiling signal handler.'''

    state.profile_level -= 1

    if state.profile_level == 0:

        if lastmechanism == b'signal':

            rpt = signal.setitimer(signal.ITIMER_PROF, 0.0, 0.0)

            signal.signal(signal.SIGPROF, signal.SIG_IGN)

            state.remaining_prof_time = rpt[0]

        elif lastmechanism == b'thread':

            stopthread.set()

            state.thread.join()

        state.accumulate_time(clock())

        state.last_start_time = None

        statprofpath = encoding.environ.get(b'STATPROF_DEST')

        if statprofpath:

            save_data(statprofpath)

    return state

def save_data(path):

    with open(path, 'w+b') as file:

        file.write(b"%f %f\n" % state.accumulated_time)

        for sample in state.samples:

            time = sample.time

            stack = sample.stack

            sites = [

                b'\1'.join([s.path, b'%d' % s.lineno or -1, s.function])

                for s in stack

            ]

            file.write(b"%d\0%s\n" % (time, b'\0'.join(sites)))

def load_data(path):

    with open(path, 'rb') as fp:

        lines = fp.read().splitlines()

    state.accumulated_time = [float(value) for value in lines[0].split()]

    state.samples = []

    for line in lines[1:]:

        parts = line.split(b'\0')

        time = float(parts[0])

        rawsites = parts[1:]

        sites = []

        for rawsite in rawsites:

            siteparts = rawsite.split(b'\1')

            sites.append(

                CodeSite.get(siteparts[0], int(siteparts[1]), siteparts[2])

            )

        state.samples.append(Sample(sites, time))

def reset(frequency=None):

    """Clear out the state of the profiler.  Do not call while the

    profiler is running.

    The optional frequency argument specifies the number of samples to

    collect per second."""

    assert state.profile_level == 0, b"Can't reset() while statprof is running"

    CodeSite.cache.clear()

    state.reset(frequency)

@contextmanager

def profile():

    start()

    try:

        yield

    finally:

        stop()

        display()

###########################################################################

## Reporting API

class SiteStats:

    def __init__(self, site):

        self.site = site

        self.selfcount = 0

        self.totalcount = 0

    def addself(self):

        self.selfcount += 1

    def addtotal(self):

        self.totalcount += 1

    def selfpercent(self):

        return self.selfcount / len(state.samples) * 100

    def totalpercent(self):

        return self.totalcount / len(state.samples) * 100

    def selfseconds(self):

        return self.selfcount * state.seconds_per_sample()

    def totalseconds(self):

        return self.totalcount * state.seconds_per_sample()

    @classmethod

    def buildstats(cls, samples):

        stats = {}

        for sample in samples:

            for i, site in enumerate(sample.stack):

                sitestat = stats.get(site)

                if not sitestat:

                    sitestat = SiteStats(site)

                    stats[site] = sitestat

                sitestat.addtotal()

                if i == 0:

                    sitestat.addself()

        return [s for s in stats.values()]

class DisplayFormats:

    ByLine = 0

    ByMethod = 1

    AboutMethod = 2

    Hotpath = 3

    FlameGraph = 4

    Json = 5

    Chrome = 6

def display(fp=None, format=3, data=None, **kwargs):

    '''Print statistics, either to stdout or the given file object.'''

    if data is None:

        data = state

    if fp is None:

        from .utils import procutil

        fp = procutil.stdout

    if len(data.samples) == 0:

        fp.write(b'No samples recorded.\n')