perfr 0.1.7__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- perfr/__init__.py +79 -0
- perfr/__main__.py +10 -0
- perfr/libperfr.dll +0 -0
- perfr/licenses/frida-core.txt +50 -0
- perfr/licenses/frida-gum.txt +118 -0
- perfr/perfr-hook.exe +4 -0
- perfr/perfr.exe +0 -0
- perfr/perfr.h +662 -0
- perfr-0.1.7.dist-info/METADATA +61 -0
- perfr-0.1.7.dist-info/RECORD +13 -0
- perfr-0.1.7.dist-info/WHEEL +5 -0
- perfr-0.1.7.dist-info/entry_points.txt +2 -0
- perfr-0.1.7.dist-info/top_level.txt +1 -0
perfr/__init__.py
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Copyright (c) 2026 The perfr Authors. All rights reserved.
|
|
2
|
+
# Use of this source code is governed by a BSD-style license that can be
|
|
3
|
+
# found in the LICENSE file.
|
|
4
|
+
|
|
5
|
+
"""perfr, the profiler, as a pip-installable package.
|
|
6
|
+
|
|
7
|
+
pip install perfr
|
|
8
|
+
perfr # then open http://127.0.0.1:44766/
|
|
9
|
+
|
|
10
|
+
The wheel carries the prebuilt ``perfr`` binary -- the capture service
|
|
11
|
+
that also serves the web viewer -- plus ``libperfr`` and ``perfr.h`` for
|
|
12
|
+
instrumenting C and C++, the Frida agent and helper the service loads from
|
|
13
|
+
the same directory, and a dependency on ``perfr-api`` so ``import perfr_api``
|
|
14
|
+
works for Python. The ``perfr`` console command runs the bundled
|
|
15
|
+
binary; ``perfr.binary_path()`` returns its location.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
import os
|
|
19
|
+
import sys
|
|
20
|
+
|
|
21
|
+
__all__ = ["binary_path", "header_path", "library_path", "main"]
|
|
22
|
+
__version__ = "0.1.7"
|
|
23
|
+
|
|
24
|
+
if sys.platform == "win32":
|
|
25
|
+
_BINARY, _LIBRARY = "perfr.exe", "libperfr.dll"
|
|
26
|
+
elif sys.platform == "darwin":
|
|
27
|
+
_BINARY, _LIBRARY = "perfr", "libperfr.dylib"
|
|
28
|
+
else:
|
|
29
|
+
_BINARY, _LIBRARY = "perfr", "libperfr.so"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _here(name):
|
|
33
|
+
return os.path.join(os.path.dirname(os.path.abspath(__file__)), name)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def binary_path():
|
|
37
|
+
"""The bundled ``perfr`` executable."""
|
|
38
|
+
return _here(_BINARY)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def library_path():
|
|
42
|
+
"""The bundled ``libperfr`` shared library, or ``None`` if absent."""
|
|
43
|
+
p = _here(_LIBRARY)
|
|
44
|
+
return p if os.path.exists(p) else None
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def header_path():
|
|
48
|
+
"""The bundled ``perfr.h``, or ``None`` if absent."""
|
|
49
|
+
p = _here("perfr.h")
|
|
50
|
+
return p if os.path.exists(p) else None
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def _ensure_executable(path):
|
|
54
|
+
"""Wheels do not keep the executable bit. A read-only install is ignored."""
|
|
55
|
+
if not os.path.exists(path):
|
|
56
|
+
return
|
|
57
|
+
try:
|
|
58
|
+
os.chmod(path, 0o755)
|
|
59
|
+
except OSError:
|
|
60
|
+
pass
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def main():
|
|
64
|
+
"""Entry point for the ``perfr`` console script: run the bundled
|
|
65
|
+
binary with this process's arguments, replacing this process where the OS
|
|
66
|
+
allows it so signals and exit codes pass straight through."""
|
|
67
|
+
binary = binary_path()
|
|
68
|
+
if not os.path.exists(binary):
|
|
69
|
+
sys.exit("perfr: the perfr binary is missing from this wheel")
|
|
70
|
+
# The service spawns perfr-hook from the same directory. Both
|
|
71
|
+
# need the executable bit, which a wheel does not record.
|
|
72
|
+
_ensure_executable(binary)
|
|
73
|
+
_ensure_executable(_here("perfr-hook"))
|
|
74
|
+
argv = [binary] + sys.argv[1:]
|
|
75
|
+
if sys.platform == "win32":
|
|
76
|
+
import subprocess
|
|
77
|
+
|
|
78
|
+
sys.exit(subprocess.call(argv))
|
|
79
|
+
os.execv(binary, argv)
|
perfr/__main__.py
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Copyright (c) 2026 The perfr Authors. All rights reserved.
|
|
2
|
+
# Use of this source code is governed by a BSD-style license that can be
|
|
3
|
+
# found in the LICENSE file.
|
|
4
|
+
|
|
5
|
+
"""`python -m perfr ...` runs the bundled perfr."""
|
|
6
|
+
|
|
7
|
+
from . import main
|
|
8
|
+
|
|
9
|
+
if __name__ == "__main__":
|
|
10
|
+
main()
|
perfr/libperfr.dll
ADDED
|
Binary file
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
wxWindows Library Licence, Version 3.1
|
|
2
|
+
======================================
|
|
3
|
+
|
|
4
|
+
Copyright (c) 1998-2005 Julian Smart, Robert Roebling et al
|
|
5
|
+
|
|
6
|
+
Everyone is permitted to copy and distribute verbatim copies
|
|
7
|
+
of this licence document, but changing it is not allowed.
|
|
8
|
+
|
|
9
|
+
WXWINDOWS LIBRARY LICENCE
|
|
10
|
+
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
|
11
|
+
|
|
12
|
+
This library is free software; you can redistribute it and/or modify it
|
|
13
|
+
under the terms of the GNU Library General Public Licence as published by
|
|
14
|
+
the Free Software Foundation; either version 2 of the Licence, or (at your
|
|
15
|
+
option) any later version.
|
|
16
|
+
|
|
17
|
+
This library is distributed in the hope that it will be useful, but WITHOUT
|
|
18
|
+
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
|
|
20
|
+
Licence for more details.
|
|
21
|
+
|
|
22
|
+
You should have received a copy of the GNU Library General Public Licence
|
|
23
|
+
along with this software, usually in a file named COPYING.LIB. If not,
|
|
24
|
+
write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
|
|
25
|
+
Floor, Boston, MA 02110-1301 USA.
|
|
26
|
+
|
|
27
|
+
EXCEPTION NOTICE
|
|
28
|
+
|
|
29
|
+
1. As a special exception, the copyright holders of this library give
|
|
30
|
+
permission for additional uses of the text contained in this release of the
|
|
31
|
+
library as licenced under the wxWindows Library Licence, applying either
|
|
32
|
+
version 3.1 of the Licence, or (at your option) any later version of the
|
|
33
|
+
Licence as published by the copyright holders of version 3.1 of the Licence
|
|
34
|
+
document.
|
|
35
|
+
|
|
36
|
+
2. The exception is that you may use, copy, link, modify and distribute
|
|
37
|
+
under your own terms, binary object code versions of works based on the
|
|
38
|
+
Library.
|
|
39
|
+
|
|
40
|
+
3. If you copy code from files distributed under the terms of the GNU
|
|
41
|
+
General Public Licence or the GNU Library General Public Licence into a
|
|
42
|
+
copy of this library, as this licence permits, the exception does not apply
|
|
43
|
+
to the code that you add in this way. To avoid misleading anyone as to the
|
|
44
|
+
status of such modified files, you must delete this exception notice from
|
|
45
|
+
such code and/or adjust the licensing conditions notice accordingly.
|
|
46
|
+
|
|
47
|
+
4. If you write modifications of your own for this library, it is your
|
|
48
|
+
choice whether to permit this exception to apply to your modifications. If
|
|
49
|
+
you do not wish that, you must delete the exception notice from such code
|
|
50
|
+
and/or adjust the licensing conditions notice accordingly.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
wxWindows Library Licence, Version 3.1
|
|
2
|
+
======================================
|
|
3
|
+
|
|
4
|
+
Copyright (c) 1998-2005 Julian Smart, Robert Roebling et al
|
|
5
|
+
|
|
6
|
+
Everyone is permitted to copy and distribute verbatim copies
|
|
7
|
+
of this licence document, but changing it is not allowed.
|
|
8
|
+
|
|
9
|
+
WXWINDOWS LIBRARY LICENCE
|
|
10
|
+
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
|
11
|
+
|
|
12
|
+
This library is free software; you can redistribute it and/or modify it
|
|
13
|
+
under the terms of the GNU Library General Public Licence as published by
|
|
14
|
+
the Free Software Foundation; either version 2 of the Licence, or (at your
|
|
15
|
+
option) any later version.
|
|
16
|
+
|
|
17
|
+
This library is distributed in the hope that it will be useful, but WITHOUT
|
|
18
|
+
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
|
|
20
|
+
Licence for more details.
|
|
21
|
+
|
|
22
|
+
You should have received a copy of the GNU Library General Public Licence
|
|
23
|
+
along with this software, usually in a file named COPYING.LIB. If not,
|
|
24
|
+
write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
|
|
25
|
+
Floor, Boston, MA 02110-1301 USA.
|
|
26
|
+
|
|
27
|
+
EXCEPTION NOTICE
|
|
28
|
+
|
|
29
|
+
1. As a special exception, the copyright holders of this library give
|
|
30
|
+
permission for additional uses of the text contained in this release of the
|
|
31
|
+
library as licenced under the wxWindows Library Licence, applying either
|
|
32
|
+
version 3.1 of the Licence, or (at your option) any later version of the
|
|
33
|
+
Licence as published by the copyright holders of version 3.1 of the Licence
|
|
34
|
+
document.
|
|
35
|
+
|
|
36
|
+
2. The exception is that you may use, copy, link, modify and distribute
|
|
37
|
+
under your own terms, binary object code versions of works based on the
|
|
38
|
+
Library.
|
|
39
|
+
|
|
40
|
+
3. If you copy code from files distributed under the terms of the GNU
|
|
41
|
+
General Public Licence or the GNU Library General Public Licence into a
|
|
42
|
+
copy of this library, as this licence permits, the exception does not apply
|
|
43
|
+
to the code that you add in this way. To avoid misleading anyone as to the
|
|
44
|
+
status of such modified files, you must delete this exception notice from
|
|
45
|
+
such code and/or adjust the licensing conditions notice accordingly.
|
|
46
|
+
|
|
47
|
+
4. If you write modifications of your own for this library, it is your
|
|
48
|
+
choice whether to permit this exception to apply to your modifications. If
|
|
49
|
+
you do not wish that, you must delete the exception notice from such code
|
|
50
|
+
and/or adjust the licensing conditions notice accordingly.
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
Portions from https://github.com/mozilla/source-map:
|
|
54
|
+
|
|
55
|
+
Copyright 2011 Mozilla Foundation and contributors
|
|
56
|
+
Licensed under the New BSD license. See LICENSE or:
|
|
57
|
+
http://opensource.org/licenses/BSD-3-Clause
|
|
58
|
+
|
|
59
|
+
Based on the Base 64 VLQ implementation in Closure Compiler:
|
|
60
|
+
https://code.google.com/p/closure-compiler/source/browse/trunk/src/com/google/debugging/sourcemap/Base64VLQ.java
|
|
61
|
+
|
|
62
|
+
Copyright 2011 The Closure Compiler Authors. All rights reserved.
|
|
63
|
+
Redistribution and use in source and binary forms, with or without
|
|
64
|
+
modification, are permitted provided that the following conditions are
|
|
65
|
+
met:
|
|
66
|
+
|
|
67
|
+
* Redistributions of source code must retain the above copyright
|
|
68
|
+
notice, this list of conditions and the following disclaimer.
|
|
69
|
+
* Redistributions in binary form must reproduce the above
|
|
70
|
+
copyright notice, this list of conditions and the following
|
|
71
|
+
disclaimer in the documentation and/or other materials provided
|
|
72
|
+
with the distribution.
|
|
73
|
+
* Neither the name of Google Inc. nor the names of its
|
|
74
|
+
contributors may be used to endorse or promote products derived
|
|
75
|
+
from this software without specific prior written permission.
|
|
76
|
+
|
|
77
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
78
|
+
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
79
|
+
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
80
|
+
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
81
|
+
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
82
|
+
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
83
|
+
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
84
|
+
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
85
|
+
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
86
|
+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
87
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
Portions from https://github.com/facebook/regenerator:
|
|
91
|
+
|
|
92
|
+
BSD License
|
|
93
|
+
|
|
94
|
+
For "regenerator" software
|
|
95
|
+
|
|
96
|
+
Copyright (c) 2014, Facebook, Inc.
|
|
97
|
+
All rights reserved.
|
|
98
|
+
|
|
99
|
+
Redistribution and use in source and binary forms, with or without modification,
|
|
100
|
+
are permitted provided that the following conditions are met:
|
|
101
|
+
|
|
102
|
+
* Redistributions of source code must retain the above copyright notice, this
|
|
103
|
+
list of conditions and the following disclaimer.
|
|
104
|
+
|
|
105
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
|
106
|
+
this list of conditions and the following disclaimer in the documentation
|
|
107
|
+
and/or other materials provided with the distribution.
|
|
108
|
+
|
|
109
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
110
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
111
|
+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
112
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
|
113
|
+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
114
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
115
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
116
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
117
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
118
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
perfr/perfr-hook.exe
ADDED
perfr/perfr.exe
ADDED
|
Binary file
|
perfr/perfr.h
ADDED
|
@@ -0,0 +1,662 @@
|
|
|
1
|
+
/* Copyright (c) 2026 The perfr Authors. All rights reserved.
|
|
2
|
+
* Use of this source code is governed by a BSD-style license that can be
|
|
3
|
+
* found in the LICENSE file. */
|
|
4
|
+
|
|
5
|
+
/* perfr manual instrumentation. One header, nothing to link.
|
|
6
|
+
*
|
|
7
|
+
* #include "perfr.h"
|
|
8
|
+
*
|
|
9
|
+
* int main(void) {
|
|
10
|
+
* perfr_init(); // finds the library, or stays quiet
|
|
11
|
+
* for (;;) {
|
|
12
|
+
* PERFR_SCOPE("frame"); // C++ RAII, or GNU C via cleanup
|
|
13
|
+
* perfr_scope s = perfr_start(PERFR_LIT("physics"));
|
|
14
|
+
* ...
|
|
15
|
+
* perfr_stop(s);
|
|
16
|
+
* PERFR_VALUE("fps", 59.9);
|
|
17
|
+
* PERFR_FRAME_MARK(); // this frame ends, the next begins
|
|
18
|
+
* }
|
|
19
|
+
* }
|
|
20
|
+
*
|
|
21
|
+
* HOW IT WORKS
|
|
22
|
+
*
|
|
23
|
+
* The producer -- the shared-memory ring that a running perfr drains
|
|
24
|
+
* -- lives in one library, libperfr, which ships beside perfr.
|
|
25
|
+
* This header never links it. perfr_init() loads it at run time, checks that
|
|
26
|
+
* it speaks this header's ABI, and fills a table of function pointers; every
|
|
27
|
+
* call below is then a load, a null check and an indirect call, about fifteen
|
|
28
|
+
* nanoseconds for a scope, most of it the clock read. When the library is not
|
|
29
|
+
* there, perfr_init() returns PERFR_E_NOLIB and every call is one predictable
|
|
30
|
+
* branch that does nothing.
|
|
31
|
+
*
|
|
32
|
+
* So an application can ship with this header compiled in and pay nothing on
|
|
33
|
+
* machines that never profile it, and the ring protocol is never frozen into
|
|
34
|
+
* an application binary: the service and the library it comes with always
|
|
35
|
+
* agree, and fixing the producer means updating the service, not rebuilding
|
|
36
|
+
* every program that includes this file.
|
|
37
|
+
*
|
|
38
|
+
* WHERE THIS HEADER IS INSTALLED
|
|
39
|
+
*
|
|
40
|
+
* Linux and macOS: ~/.local/include/perfr.h. Compile with -I~/.local/include.
|
|
41
|
+
* If PERFR_INSTALL_DIR overrides the bin directory, the header is that
|
|
42
|
+
* directory's sibling ../include/perfr.h. Windows: <install dir>\include\perfr.h
|
|
43
|
+
* (default %LOCALAPPDATA%\Programs\perfr\include\perfr.h). The header is not
|
|
44
|
+
* installed beside the perfr binary. This file does not look for the library
|
|
45
|
+
* next to itself.
|
|
46
|
+
*
|
|
47
|
+
* WHERE THE LIBRARY IS LOOKED FOR, IN ORDER
|
|
48
|
+
*
|
|
49
|
+
* libperfr still ships beside perfr. perfr_init() finds that copy by
|
|
50
|
+
* searching PATH for the perfr binary, not by looking next to this header.
|
|
51
|
+
*
|
|
52
|
+
* 1. $PERFR_LIB the full path of the library file. When set it
|
|
53
|
+
* is the only place tried, so a wrong path fails
|
|
54
|
+
* visibly instead of loading some other copy.
|
|
55
|
+
* 2. beside perfr every $PATH directory that holds a perfr,
|
|
56
|
+
* then ~/.local/bin (where install.sh puts the
|
|
57
|
+
* binary) and ~/.perfr/bin. The service is the
|
|
58
|
+
* authority on the ring protocol version -- it
|
|
59
|
+
* refuses a segment written at any other -- so
|
|
60
|
+
* its own library wins over a copy shipped beside
|
|
61
|
+
* an application.
|
|
62
|
+
* 3. beside the executable <directory of the running program>/libperfr.so,
|
|
63
|
+
* for a machine with no service installed.
|
|
64
|
+
* 4. the system loader dlopen("libperfr.so")
|
|
65
|
+
*
|
|
66
|
+
* .dylib on macOS; libperfr.dll, %PATH% and LoadLibrary on Windows.
|
|
67
|
+
*
|
|
68
|
+
* STATIC BUILDS
|
|
69
|
+
*
|
|
70
|
+
* #define PERFR_STATIC before including this header to skip the loader and
|
|
71
|
+
* declare the functions as ordinary externs, then link libperfr_api.a. For
|
|
72
|
+
* musl and other targets without dlopen. The calls in your code do not change.
|
|
73
|
+
*
|
|
74
|
+
* REQUIREMENTS
|
|
75
|
+
*
|
|
76
|
+
* C99 or C++11; GCC, Clang or MSVC in dynamic mode (a process-wide table slot
|
|
77
|
+
* needs weak or selectany linkage; any compiler in static mode). The dynamic
|
|
78
|
+
* mode includes <dlfcn.h> and <unistd.h>, so glibc older than 2.34 wants -ldl
|
|
79
|
+
* on the link line. A strict -std=c99 or -std=c11 works as is.
|
|
80
|
+
*
|
|
81
|
+
* Every function is safe to call from any thread at any time, including
|
|
82
|
+
* before perfr_init() and after perfr_shutdown(). Names are passed as pointer
|
|
83
|
+
* and length, never as NUL-terminated strings, so a Rust &str or a Python
|
|
84
|
+
* bytes object crosses without a copy or a scan; PERFR_LIT() spells a literal.
|
|
85
|
+
* Names travel in full and are never interned: a segment describes itself. */
|
|
86
|
+
|
|
87
|
+
#ifndef PERFR_API_H
|
|
88
|
+
#define PERFR_API_H
|
|
89
|
+
|
|
90
|
+
#include <stddef.h>
|
|
91
|
+
#include <stdint.h>
|
|
92
|
+
|
|
93
|
+
#ifdef __cplusplus
|
|
94
|
+
extern "C" {
|
|
95
|
+
#endif
|
|
96
|
+
|
|
97
|
+
/* The ABI this header speaks. The library hands out its table only for the
|
|
98
|
+
* version it was built for; anything else stays no-op instead of calling
|
|
99
|
+
* through a layout it does not have. */
|
|
100
|
+
#define PERFR_API_ABI_VERSION 1u
|
|
101
|
+
|
|
102
|
+
/* perfr_init() results beyond 0 (ok) and -errno (the segment could not be
|
|
103
|
+
* created). Instrumentation calls stay valid no-ops in every case. */
|
|
104
|
+
#define PERFR_E_NOLIB (-1000) /* no libperfr found: see the search order above */
|
|
105
|
+
#define PERFR_E_ABI (-1001) /* a libperfr was found but speaks another ABI */
|
|
106
|
+
|
|
107
|
+
/* A handle to an event this process recorded: a scope from perfr_start, or an
|
|
108
|
+
* instant. It is an identity, not a resource -- nothing needs to be freed --
|
|
109
|
+
* and it is what perfr_stop and perfr_link take, from any thread. Zero means
|
|
110
|
+
* "no event", which is what every call returns while profiling is off, and
|
|
111
|
+
* every function accepts zero and does nothing. */
|
|
112
|
+
typedef uint64_t perfr_scope;
|
|
113
|
+
|
|
114
|
+
/* Every entry point, as the library publishes it. Mirrors ApiTableV1 in the
|
|
115
|
+
* perfr-api crate field for field; `size` lets a newer header recognise an
|
|
116
|
+
* older table. Callers never touch this directly. */
|
|
117
|
+
struct perfr_api_table_v1 {
|
|
118
|
+
uint32_t abi_version;
|
|
119
|
+
uint32_t size;
|
|
120
|
+
int (*init)(void);
|
|
121
|
+
void (*shutdown)(void);
|
|
122
|
+
perfr_scope (*start)(const char* name, size_t name_len);
|
|
123
|
+
perfr_scope (*start_dynamic)(const char* name, size_t name_len);
|
|
124
|
+
perfr_scope (*start_async)(const char* name, size_t name_len);
|
|
125
|
+
void (*stop)(perfr_scope scope);
|
|
126
|
+
perfr_scope (*instant)(const char* name, size_t name_len);
|
|
127
|
+
void (*link)(perfr_scope from, perfr_scope to);
|
|
128
|
+
void (*value)(const char* name, size_t name_len, double value);
|
|
129
|
+
uint64_t (*now_ns)(void);
|
|
130
|
+
void (*span)(const char* name, size_t name_len, uint64_t start_ns, uint64_t end_ns);
|
|
131
|
+
void (*span_async)(const char* name, size_t name_len, uint64_t start_ns, uint64_t end_ns);
|
|
132
|
+
/* Appended after the first release of this table. Everything above this
|
|
133
|
+
* line is what a library must provide to load at all
|
|
134
|
+
* (PERFR_API_TABLE_BASE_SIZE_); a field below it is read only when the
|
|
135
|
+
* library's `size` covers it, so a library built before logging still
|
|
136
|
+
* loads and perfr_log stays a no-op against it. */
|
|
137
|
+
void (*log)(uint8_t level, const char* message, size_t message_len);
|
|
138
|
+
/* Appended after log, and checked the same way. */
|
|
139
|
+
void (*frame_mark)(const char* name, size_t name_len);
|
|
140
|
+
};
|
|
141
|
+
|
|
142
|
+
/* The table as first released: the fields every library has. */
|
|
143
|
+
#define PERFR_API_TABLE_BASE_SIZE_ offsetof(struct perfr_api_table_v1, log)
|
|
144
|
+
/* Whether table `t` is long enough to hold `field`. */
|
|
145
|
+
#define PERFR_API_HAS_(t, field) \
|
|
146
|
+
((t)->size >= offsetof(struct perfr_api_table_v1, field) + \
|
|
147
|
+
sizeof(((const struct perfr_api_table_v1*)0)->field))
|
|
148
|
+
|
|
149
|
+
#ifdef PERFR_STATIC
|
|
150
|
+
|
|
151
|
+
/* ------------------------------------------------------------ static mode --
|
|
152
|
+
* The functions are ordinary symbols in libperfr_api.a. What each one does is
|
|
153
|
+
* documented on its dynamic-mode twin below. */
|
|
154
|
+
|
|
155
|
+
int perfr_init(void);
|
|
156
|
+
void perfr_shutdown(void);
|
|
157
|
+
perfr_scope perfr_start(const char* name, size_t name_len);
|
|
158
|
+
perfr_scope perfr_start_dynamic(const char* name, size_t name_len);
|
|
159
|
+
perfr_scope perfr_start_async(const char* name, size_t name_len);
|
|
160
|
+
void perfr_stop(perfr_scope scope);
|
|
161
|
+
perfr_scope perfr_instant(const char* name, size_t name_len);
|
|
162
|
+
void perfr_link(perfr_scope from, perfr_scope to);
|
|
163
|
+
void perfr_value(const char* name, size_t name_len, double value);
|
|
164
|
+
uint64_t perfr_now_ns(void);
|
|
165
|
+
void perfr_span(const char* name, size_t name_len, uint64_t start_ns, uint64_t end_ns);
|
|
166
|
+
void perfr_span_async(const char* name, size_t name_len, uint64_t start_ns, uint64_t end_ns);
|
|
167
|
+
void perfr_log(uint8_t level, const char* message, size_t message_len);
|
|
168
|
+
void perfr_frame_mark(const char* name, size_t name_len);
|
|
169
|
+
|
|
170
|
+
/* Whether a library is loaded and the process has a segment. Always 1 here:
|
|
171
|
+
* the library is linked in. */
|
|
172
|
+
static inline int perfr_available(void) { return 1; }
|
|
173
|
+
|
|
174
|
+
#ifdef __cplusplus
|
|
175
|
+
} /* extern "C" */
|
|
176
|
+
#endif
|
|
177
|
+
|
|
178
|
+
#else /* PERFR_STATIC */
|
|
179
|
+
|
|
180
|
+
/* ----------------------------------------------------------- dynamic mode --
|
|
181
|
+
* One table pointer per linked module, defined here and collapsed across
|
|
182
|
+
* every translation unit of that module by the linker (weak on ELF and
|
|
183
|
+
* Mach-O, selectany on COFF). It lives inside extern "C" so C and C++ files
|
|
184
|
+
* in the same module share the one slot.
|
|
185
|
+
*
|
|
186
|
+
* Per module, not per process: on Windows every DLL that includes this
|
|
187
|
+
* header has a slot of its own, and so does an ELF shared object built with
|
|
188
|
+
* hidden visibility. Each such module calls perfr_init() itself; they all
|
|
189
|
+
* end up with the same library and the same segment. */
|
|
190
|
+
|
|
191
|
+
#if defined(_MSC_VER)
|
|
192
|
+
#define PERFR_SHARED_ __declspec(selectany)
|
|
193
|
+
#elif defined(__GNUC__) || defined(__clang__)
|
|
194
|
+
#define PERFR_SHARED_ __attribute__((weak))
|
|
195
|
+
#else
|
|
196
|
+
#error "perfr.h dynamic mode needs GCC, Clang or MSVC; define PERFR_STATIC and link libperfr instead"
|
|
197
|
+
#endif
|
|
198
|
+
|
|
199
|
+
PERFR_SHARED_ const struct perfr_api_table_v1* perfr_api_table_v1_ = 0;
|
|
200
|
+
|
|
201
|
+
#ifdef __cplusplus
|
|
202
|
+
} /* extern "C" */
|
|
203
|
+
#endif
|
|
204
|
+
|
|
205
|
+
#include <stdlib.h>
|
|
206
|
+
#include <string.h>
|
|
207
|
+
|
|
208
|
+
#if defined(_WIN32)
|
|
209
|
+
#ifndef WIN32_LEAN_AND_MEAN
|
|
210
|
+
#define WIN32_LEAN_AND_MEAN
|
|
211
|
+
#endif
|
|
212
|
+
#include <windows.h>
|
|
213
|
+
#if defined(_MSC_VER)
|
|
214
|
+
/* getenv is what this header needs; the _dupenv_s MSVC suggests allocates. */
|
|
215
|
+
#pragma warning(push)
|
|
216
|
+
#pragma warning(disable : 4996)
|
|
217
|
+
#endif
|
|
218
|
+
#define PERFR_LIB_FILE_ "libperfr.dll"
|
|
219
|
+
#define PERFR_SERVICE_FILE_ "perfr.exe"
|
|
220
|
+
#define PERFR_PATH_SEP_ ';'
|
|
221
|
+
#define PERFR_DIR_SEP_ '\\'
|
|
222
|
+
#else
|
|
223
|
+
#include <dlfcn.h>
|
|
224
|
+
#include <unistd.h>
|
|
225
|
+
#if defined(__APPLE__)
|
|
226
|
+
#include <mach-o/dyld.h>
|
|
227
|
+
#define PERFR_LIB_FILE_ "libperfr.dylib"
|
|
228
|
+
#else
|
|
229
|
+
#define PERFR_LIB_FILE_ "libperfr.so"
|
|
230
|
+
#if !defined(__cplusplus)
|
|
231
|
+
/* Under a strict -std=c99/c11 glibc hides readlink behind the XOPEN feature
|
|
232
|
+
* gate, and this header cannot set that before system headers a program
|
|
233
|
+
* included first. A redeclaration with the same type is legal C and merges
|
|
234
|
+
* with glibc's own when that one is visible. (g++ defines _GNU_SOURCE.) */
|
|
235
|
+
extern ssize_t readlink(const char* path, char* buf, size_t len);
|
|
236
|
+
#endif
|
|
237
|
+
#endif
|
|
238
|
+
#define PERFR_SERVICE_FILE_ "perfr"
|
|
239
|
+
#define PERFR_PATH_SEP_ ':'
|
|
240
|
+
#define PERFR_DIR_SEP_ '/'
|
|
241
|
+
#endif
|
|
242
|
+
|
|
243
|
+
/* The pointer is published once, after the library is mapped and initialised,
|
|
244
|
+
* and read on every call. Acquire on the read side is what lets a thread that
|
|
245
|
+
* never called perfr_init() see the library the initialising thread mapped. */
|
|
246
|
+
static inline const struct perfr_api_table_v1* perfr_api_get_(void) {
|
|
247
|
+
#if defined(__GNUC__) || defined(__clang__)
|
|
248
|
+
return __atomic_load_n(&perfr_api_table_v1_, __ATOMIC_ACQUIRE);
|
|
249
|
+
#else
|
|
250
|
+
return *(const struct perfr_api_table_v1* volatile*)&perfr_api_table_v1_;
|
|
251
|
+
#endif
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
static inline void perfr_api_set_(const struct perfr_api_table_v1* table) {
|
|
255
|
+
#if defined(__GNUC__) || defined(__clang__)
|
|
256
|
+
__atomic_store_n(&perfr_api_table_v1_, table, __ATOMIC_RELEASE);
|
|
257
|
+
#else
|
|
258
|
+
MemoryBarrier();
|
|
259
|
+
*(const struct perfr_api_table_v1* volatile*)&perfr_api_table_v1_ = table;
|
|
260
|
+
#endif
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/* --- the loader ---------------------------------------------------------- */
|
|
264
|
+
|
|
265
|
+
static inline void* perfr_api_dlopen_(const char* path) {
|
|
266
|
+
#if defined(_WIN32)
|
|
267
|
+
return (void*)LoadLibraryA(path);
|
|
268
|
+
#else
|
|
269
|
+
return dlopen(path, RTLD_NOW | RTLD_LOCAL);
|
|
270
|
+
#endif
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
static inline void perfr_api_dlclose_(void* handle) {
|
|
274
|
+
#if defined(_WIN32)
|
|
275
|
+
FreeLibrary((HMODULE)handle);
|
|
276
|
+
#else
|
|
277
|
+
dlclose(handle);
|
|
278
|
+
#endif
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
static inline int perfr_api_file_exists_(const char* path) {
|
|
282
|
+
#if defined(_WIN32)
|
|
283
|
+
return GetFileAttributesA(path) != INVALID_FILE_ATTRIBUTES;
|
|
284
|
+
#else
|
|
285
|
+
return access(path, F_OK) == 0;
|
|
286
|
+
#endif
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/* dir + separator + file into buf. 0 when it does not fit. */
|
|
290
|
+
static inline int perfr_api_join_(char* buf, size_t cap, const char* dir, size_t dir_len,
|
|
291
|
+
const char* file) {
|
|
292
|
+
size_t file_len = strlen(file);
|
|
293
|
+
if (dir_len == 0 || dir_len + 1 + file_len + 1 > cap) return 0;
|
|
294
|
+
memcpy(buf, dir, dir_len);
|
|
295
|
+
buf[dir_len] = PERFR_DIR_SEP_;
|
|
296
|
+
memcpy(buf + dir_len + 1, file, file_len + 1);
|
|
297
|
+
return 1;
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
static inline void* perfr_api_open_in_(const char* dir, size_t dir_len) {
|
|
301
|
+
char path[4096];
|
|
302
|
+
if (!perfr_api_join_(path, sizeof path, dir, dir_len, PERFR_LIB_FILE_)) return 0;
|
|
303
|
+
if (!perfr_api_file_exists_(path)) return 0;
|
|
304
|
+
return perfr_api_dlopen_(path);
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/* The directory of the running executable, without its trailing separator.
|
|
308
|
+
* 0 when it cannot be found, which is not an error, only a rule skipped. */
|
|
309
|
+
static inline size_t perfr_api_exe_dir_(char* buf, size_t cap) {
|
|
310
|
+
char* slash;
|
|
311
|
+
#if defined(_WIN32)
|
|
312
|
+
DWORD n = GetModuleFileNameA(NULL, buf, (DWORD)cap);
|
|
313
|
+
if (n == 0 || n >= cap) return 0;
|
|
314
|
+
#elif defined(__APPLE__)
|
|
315
|
+
uint32_t n = (uint32_t)cap;
|
|
316
|
+
if (_NSGetExecutablePath(buf, &n) != 0) return 0;
|
|
317
|
+
buf[cap - 1] = 0;
|
|
318
|
+
#else
|
|
319
|
+
ssize_t n = readlink("/proc/self/exe", buf, cap - 1);
|
|
320
|
+
if (n <= 0) return 0;
|
|
321
|
+
buf[n] = 0;
|
|
322
|
+
#endif
|
|
323
|
+
slash = strrchr(buf, PERFR_DIR_SEP_);
|
|
324
|
+
if (!slash) return 0;
|
|
325
|
+
*slash = 0;
|
|
326
|
+
return (size_t)(slash - buf);
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/* Rule 2: the directory that holds perfr. On PATH first, because that
|
|
330
|
+
* is where a running service most likely came from; then the install script's
|
|
331
|
+
* default and the directory the service uses when it installs itself. */
|
|
332
|
+
static inline void* perfr_api_open_beside_service_(void) {
|
|
333
|
+
char dir[4096];
|
|
334
|
+
char probe[4096];
|
|
335
|
+
const char* path = getenv("PATH");
|
|
336
|
+
const char* home;
|
|
337
|
+
void* handle;
|
|
338
|
+
while (path && *path) {
|
|
339
|
+
const char* end = strchr(path, PERFR_PATH_SEP_);
|
|
340
|
+
size_t len = end ? (size_t)(end - path) : strlen(path);
|
|
341
|
+
if (len > 0 && len < sizeof dir) {
|
|
342
|
+
memcpy(dir, path, len);
|
|
343
|
+
dir[len] = 0;
|
|
344
|
+
if (perfr_api_join_(probe, sizeof probe, dir, len, PERFR_SERVICE_FILE_) &&
|
|
345
|
+
perfr_api_file_exists_(probe)) {
|
|
346
|
+
handle = perfr_api_open_in_(dir, len);
|
|
347
|
+
if (handle) return handle;
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
if (!end) break;
|
|
351
|
+
path = end + 1;
|
|
352
|
+
}
|
|
353
|
+
#if defined(_WIN32)
|
|
354
|
+
home = getenv("USERPROFILE");
|
|
355
|
+
#else
|
|
356
|
+
home = getenv("HOME");
|
|
357
|
+
#endif
|
|
358
|
+
if (home && *home) {
|
|
359
|
+
static const char* const subdirs[] = {
|
|
360
|
+
#if defined(_WIN32)
|
|
361
|
+
"\\.perfr\\bin",
|
|
362
|
+
#else
|
|
363
|
+
"/.local/bin", "/.perfr/bin",
|
|
364
|
+
#endif
|
|
365
|
+
};
|
|
366
|
+
size_t i;
|
|
367
|
+
for (i = 0; i < sizeof subdirs / sizeof subdirs[0]; i++) {
|
|
368
|
+
size_t home_len = strlen(home), sub_len = strlen(subdirs[i]);
|
|
369
|
+
if (home_len + sub_len + 1 > sizeof dir) continue;
|
|
370
|
+
memcpy(dir, home, home_len);
|
|
371
|
+
memcpy(dir + home_len, subdirs[i], sub_len + 1);
|
|
372
|
+
handle = perfr_api_open_in_(dir, home_len + sub_len);
|
|
373
|
+
if (handle) return handle;
|
|
374
|
+
}
|
|
375
|
+
}
|
|
376
|
+
return 0;
|
|
377
|
+
}
|
|
378
|
+
|
|
379
|
+
static inline void* perfr_api_find_(void) {
|
|
380
|
+
char dir[4096];
|
|
381
|
+
size_t len;
|
|
382
|
+
void* handle;
|
|
383
|
+
const char* env = getenv("PERFR_LIB");
|
|
384
|
+
/* Rule 1 is exclusive: an explicit path that fails must not be papered over
|
|
385
|
+
* by a stray copy found some other way. */
|
|
386
|
+
if (env && *env) return perfr_api_dlopen_(env);
|
|
387
|
+
/* Rule 2 before rule 3: a service's library is the one guaranteed to match
|
|
388
|
+
* the service that will read the segment; a copy beside the application is
|
|
389
|
+
* the fallback for a machine that has no service installed. */
|
|
390
|
+
handle = perfr_api_open_beside_service_();
|
|
391
|
+
if (handle) return handle;
|
|
392
|
+
len = perfr_api_exe_dir_(dir, sizeof dir);
|
|
393
|
+
if (len) {
|
|
394
|
+
handle = perfr_api_open_in_(dir, len);
|
|
395
|
+
if (handle) return handle;
|
|
396
|
+
}
|
|
397
|
+
return perfr_api_dlopen_(PERFR_LIB_FILE_);
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
typedef const struct perfr_api_table_v1* (*perfr_api_table_fn_)(uint32_t abi_version);
|
|
401
|
+
|
|
402
|
+
/* Loads the library and asks it for the table. On failure *status says why
|
|
403
|
+
* and the library, if one was opened, is closed again. */
|
|
404
|
+
static inline const struct perfr_api_table_v1* perfr_api_load_(int* status) {
|
|
405
|
+
const struct perfr_api_table_v1* table;
|
|
406
|
+
perfr_api_table_fn_ get = 0;
|
|
407
|
+
void* handle = perfr_api_find_();
|
|
408
|
+
if (!handle) {
|
|
409
|
+
*status = PERFR_E_NOLIB;
|
|
410
|
+
return 0;
|
|
411
|
+
}
|
|
412
|
+
{
|
|
413
|
+
/* An object pointer is not a function pointer in ISO C; POSIX promises
|
|
414
|
+
* the bytes convert, and memcpy says so without a warning. */
|
|
415
|
+
#if defined(_WIN32)
|
|
416
|
+
FARPROC sym = GetProcAddress((HMODULE)handle, "perfr_api_table_v1");
|
|
417
|
+
#else
|
|
418
|
+
void* sym = dlsym(handle, "perfr_api_table_v1");
|
|
419
|
+
#endif
|
|
420
|
+
if (sym) memcpy(&get, &sym, sizeof get);
|
|
421
|
+
}
|
|
422
|
+
/* A library too old to have the getter speaks an older ABI by definition. */
|
|
423
|
+
table = get ? get(PERFR_API_ABI_VERSION) : 0;
|
|
424
|
+
/* Only the base table is required. Fields appended since are checked one
|
|
425
|
+
* by one where they are called, so an older library keeps working. */
|
|
426
|
+
if (!table || table->abi_version != PERFR_API_ABI_VERSION ||
|
|
427
|
+
table->size < PERFR_API_TABLE_BASE_SIZE_) {
|
|
428
|
+
perfr_api_dlclose_(handle);
|
|
429
|
+
*status = PERFR_E_ABI;
|
|
430
|
+
return 0;
|
|
431
|
+
}
|
|
432
|
+
return table;
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
/* --- the API ------------------------------------------------------------- */
|
|
436
|
+
|
|
437
|
+
/* Finds and loads libperfr (see the search order at the top), then
|
|
438
|
+
* creates this process's segment so a running perfr can find it.
|
|
439
|
+
* Idempotent. Returns 0 on success, PERFR_E_NOLIB or PERFR_E_ABI when no
|
|
440
|
+
* usable library was found, or a negative errno if the segment could not be
|
|
441
|
+
* created; instrumentation calls stay valid no-ops in every case.
|
|
442
|
+
*
|
|
443
|
+
* Call it once, early, from the main thread. Concurrent calls are harmless --
|
|
444
|
+
* both map the same library and publish the same table -- and a thread that
|
|
445
|
+
* never called it sees the table the moment it is published.
|
|
446
|
+
*
|
|
447
|
+
* A child made by fork() does not inherit the segment: every call in it is a
|
|
448
|
+
* no-op until it calls perfr_init() itself, which gives it one of its own. A
|
|
449
|
+
* program that daemonises, or forks workers, calls perfr_init() in the
|
|
450
|
+
* process that goes on to do the work. After perfr_shutdown(), perfr_init()
|
|
451
|
+
* makes a new segment. */
|
|
452
|
+
static inline int perfr_init(void) {
|
|
453
|
+
int status = 0;
|
|
454
|
+
const struct perfr_api_table_v1* table = perfr_api_get_();
|
|
455
|
+
if (!table) {
|
|
456
|
+
table = perfr_api_load_(&status);
|
|
457
|
+
if (!table) return status;
|
|
458
|
+
perfr_api_set_(table);
|
|
459
|
+
}
|
|
460
|
+
return table->init();
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
/* Removes the segment's name so a later process with the same pid starts
|
|
464
|
+
* clean. Safe to skip: a process that exits without calling this leaves a
|
|
465
|
+
* segment the service sweeps once the pid is gone. The library stays mapped,
|
|
466
|
+
* so a thread mid-call never dereferences unmapped code. */
|
|
467
|
+
static inline void perfr_shutdown(void) {
|
|
468
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
469
|
+
if (t) t->shutdown();
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
/* Whether a library is loaded, i.e. perfr_init() found one. A cheap way for
|
|
473
|
+
* a program to decide whether to bother formatting expensive scope names. */
|
|
474
|
+
static inline int perfr_available(void) { return perfr_api_get_() != 0; }
|
|
475
|
+
|
|
476
|
+
/* Begins a scope on the calling thread. Nesting is worked out by the reader
|
|
477
|
+
* from the order of starts and stops on that thread, so a scope that is
|
|
478
|
+
* never stopped costs nothing but itself: it does not skew the depth of
|
|
479
|
+
* anything after it. */
|
|
480
|
+
static inline perfr_scope perfr_start(const char* name, size_t name_len) {
|
|
481
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
482
|
+
return t ? t->start(name, name_len) : 0;
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
/* Same stream and handles as perfr_start, tagged as dynamic instrumentation.
|
|
486
|
+
* What an injected hook calls; ordinary code wants perfr_start. */
|
|
487
|
+
static inline perfr_scope perfr_start_dynamic(const char* name, size_t name_len) {
|
|
488
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
489
|
+
return t ? t->start_dynamic(name, name_len) : 0;
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
/* Begins a scope that may be stopped from any thread, drawn on its own
|
|
493
|
+
* track rather than nested in the starting thread's. This is the "File IO
|
|
494
|
+
* request site / result site" case. */
|
|
495
|
+
static inline perfr_scope perfr_start_async(const char* name, size_t name_len) {
|
|
496
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
497
|
+
return t ? t->start_async(name, name_len) : 0;
|
|
498
|
+
}
|
|
499
|
+
|
|
500
|
+
/* Ends a scope from perfr_start or perfr_start_async. The handle carries
|
|
501
|
+
* everything needed to match it, so this may be called from any thread. */
|
|
502
|
+
static inline void perfr_stop(perfr_scope scope) {
|
|
503
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
504
|
+
if (t) t->stop(scope);
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
/* A point in time with a name and no duration: "level loaded", a signal
|
|
508
|
+
* fired. Drawn as a tick, not a bar. Returns a handle so an instant can be
|
|
509
|
+
* either end of a link. A frame boundary is not an instant: see
|
|
510
|
+
* perfr_frame_mark. */
|
|
511
|
+
static inline perfr_scope perfr_instant(const char* name, size_t name_len) {
|
|
512
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
513
|
+
return t ? t->instant(name, name_len) : 0;
|
|
514
|
+
}
|
|
515
|
+
|
|
516
|
+
/* Draws an arrow from one event to another, across threads if need be.
|
|
517
|
+
*
|
|
518
|
+
* Both handles must already exist, which they will in every pattern this is
|
|
519
|
+
* for: a job enqueued on one thread and run on another carries the enqueue
|
|
520
|
+
* handle in the job; a signal sent on one thread and received on another
|
|
521
|
+
* carries it in the message. There is no separate flow id to invent -- the
|
|
522
|
+
* handle is the identity, and a link is a relation between two of them.
|
|
523
|
+
* Chains are links in sequence. */
|
|
524
|
+
static inline void perfr_link(perfr_scope from, perfr_scope to) {
|
|
525
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
526
|
+
if (t) t->link(from, to);
|
|
527
|
+
}
|
|
528
|
+
|
|
529
|
+
/* A value to graph over time, on a track named `name`. Every numeric type is
|
|
530
|
+
* a double here; integers above 2^53 lose precision, which is acceptable for
|
|
531
|
+
* something whose purpose is to be plotted. */
|
|
532
|
+
static inline void perfr_value(const char* name, size_t name_len, double value) {
|
|
533
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
534
|
+
if (t) t->value(name, name_len, value);
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
/* CLOCK_MONOTONIC in nanoseconds -- the clock every timestamp in the segment
|
|
538
|
+
* uses. Grab it at the real site of an event, then hand it to perfr_span
|
|
539
|
+
* later so the span lines up with scheduling, samples and other scopes.
|
|
540
|
+
* 0 while no library is loaded. */
|
|
541
|
+
static inline uint64_t perfr_now_ns(void) {
|
|
542
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
543
|
+
return t ? t->now_ns() : 0;
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/* Records a complete scope whose timestamps you supply, rather than reading
|
|
547
|
+
* the clock now. For events that already happened at a time captured
|
|
548
|
+
* elsewhere: GPU work whose timestamps are read back after the fact, a trace
|
|
549
|
+
* being replayed, events buffered and flushed in a batch. Timestamps are
|
|
550
|
+
* perfr_now_ns()'s clock.
|
|
551
|
+
*
|
|
552
|
+
* Nesting depth still comes from emission order, so for nested imported data,
|
|
553
|
+
* emit a parent span around its children. */
|
|
554
|
+
static inline void perfr_span(const char* name, size_t name_len, uint64_t start_ns,
|
|
555
|
+
uint64_t end_ns) {
|
|
556
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
557
|
+
if (t) t->span(name, name_len, start_ns, end_ns);
|
|
558
|
+
}
|
|
559
|
+
|
|
560
|
+
/* A complete async span at supplied timestamps, drawn on its own track -- the
|
|
561
|
+
* right one for GPU spans, independent of any CPU thread's nesting. */
|
|
562
|
+
static inline void perfr_span_async(const char* name, size_t name_len, uint64_t start_ns,
|
|
563
|
+
uint64_t end_ns) {
|
|
564
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
565
|
+
if (t) t->span_async(name, name_len, start_ns, end_ns);
|
|
566
|
+
}
|
|
567
|
+
|
|
568
|
+
/* Records a log line at `level` (PERFR_LOG_*). A no-op when nobody is
|
|
569
|
+
* capturing, and against a library built before logging. */
|
|
570
|
+
static inline void perfr_log(uint8_t level, const char* message, size_t message_len) {
|
|
571
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
572
|
+
if (t && PERFR_API_HAS_(t, log) && t->log) t->log(level, message, message_len);
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
/* Marks a frame boundary: the frame that was running ends here and the next
|
|
576
|
+
* one begins. Call it once per frame, at the same point of the loop each
|
|
577
|
+
* time. The viewer draws the time between two marks as one frame, on a
|
|
578
|
+
* `frames` lane under the calling thread, and a line down the timeline at
|
|
579
|
+
* each mark.
|
|
580
|
+
*
|
|
581
|
+
* `name` says which series of frames the mark belongs to, for a program with
|
|
582
|
+
* more than one loop: a render thread's frames, a fixed-step simulation's
|
|
583
|
+
* ticks. Each name is one series with a lane of its own. A null or empty
|
|
584
|
+
* name is the main series; PERFR_FRAME_MARK() marks it.
|
|
585
|
+
*
|
|
586
|
+
* A no-op when nobody is capturing, and against a library built before
|
|
587
|
+
* frame marks. */
|
|
588
|
+
static inline void perfr_frame_mark(const char* name, size_t name_len) {
|
|
589
|
+
const struct perfr_api_table_v1* t = perfr_api_get_();
|
|
590
|
+
if (t && PERFR_API_HAS_(t, frame_mark) && t->frame_mark) t->frame_mark(name, name_len);
|
|
591
|
+
}
|
|
592
|
+
|
|
593
|
+
#endif /* PERFR_STATIC */
|
|
594
|
+
|
|
595
|
+
/* --------------------------------------------------------------------------
|
|
596
|
+
* Convenience for C and C++. Everything below is sugar over the functions
|
|
597
|
+
* above; other languages provide their own. */
|
|
598
|
+
|
|
599
|
+
/* A string literal's length at compile time; use strlen for anything else. */
|
|
600
|
+
#define PERFR_LIT(s) (s), (sizeof(s) - 1)
|
|
601
|
+
|
|
602
|
+
#define PERFR_INSTANT(lit) ((void)perfr_instant(PERFR_LIT(lit)))
|
|
603
|
+
#define PERFR_VALUE(lit, v) perfr_value(PERFR_LIT(lit), (double)(v))
|
|
604
|
+
#define PERFR_SPAN(lit, start_ns, end_ns) perfr_span(PERFR_LIT(lit), (start_ns), (end_ns))
|
|
605
|
+
|
|
606
|
+
/* Log levels. A line carries one of these, plus its thread and timestamp. */
|
|
607
|
+
#define PERFR_LOG_TRACE 0u
|
|
608
|
+
#define PERFR_LOG_DEBUG 1u
|
|
609
|
+
#define PERFR_LOG_INFO 2u
|
|
610
|
+
#define PERFR_LOG_WARN 3u
|
|
611
|
+
#define PERFR_LOG_ERROR 4u
|
|
612
|
+
#define PERFR_LOG_FATAL 5u
|
|
613
|
+
|
|
614
|
+
#define PERFR_LOG(level, lit) perfr_log((uint8_t)(level), PERFR_LIT(lit))
|
|
615
|
+
|
|
616
|
+
/* The end of one frame and the start of the next: of the main series, or of
|
|
617
|
+
* the series called `lit`. */
|
|
618
|
+
#define PERFR_FRAME_MARK() perfr_frame_mark((const char*)0, 0)
|
|
619
|
+
#define PERFR_FRAME_MARK_NAMED(lit) perfr_frame_mark(PERFR_LIT(lit))
|
|
620
|
+
|
|
621
|
+
#define PERFR_CONCAT_(a, b) a##b
|
|
622
|
+
#define PERFR_CONCAT(a, b) PERFR_CONCAT_(a, b)
|
|
623
|
+
|
|
624
|
+
#ifdef __cplusplus
|
|
625
|
+
namespace perfr {
|
|
626
|
+
|
|
627
|
+
/* RAII scope: `perfr::Scope s("update");` or `PERFR_SCOPE("update");`. */
|
|
628
|
+
class Scope {
|
|
629
|
+
public:
|
|
630
|
+
explicit Scope(const char* name, size_t len) : handle_(perfr_start(name, len)) {}
|
|
631
|
+
~Scope() { perfr_stop(handle_); }
|
|
632
|
+
Scope(const Scope&) = delete;
|
|
633
|
+
Scope& operator=(const Scope&) = delete;
|
|
634
|
+
|
|
635
|
+
/* For perfr_link: `perfr_link(job.trace, running.handle())`. */
|
|
636
|
+
perfr_scope handle() const { return handle_; }
|
|
637
|
+
|
|
638
|
+
private:
|
|
639
|
+
perfr_scope handle_;
|
|
640
|
+
};
|
|
641
|
+
|
|
642
|
+
} /* namespace perfr */
|
|
643
|
+
|
|
644
|
+
#define PERFR_SCOPE(lit) ::perfr::Scope PERFR_CONCAT(perfr_scope_, __LINE__)(PERFR_LIT(lit))
|
|
645
|
+
|
|
646
|
+
#elif defined(__GNUC__) || defined(__clang__)
|
|
647
|
+
|
|
648
|
+
/* The same one-liner in C, where GCC and Clang can run a function when a
|
|
649
|
+
* local goes out of scope. Other C compilers pair perfr_start and perfr_stop
|
|
650
|
+
* by hand. */
|
|
651
|
+
static inline void perfr_scope_cleanup_(const perfr_scope* scope) { perfr_stop(*scope); }
|
|
652
|
+
#define PERFR_SCOPE(lit) \
|
|
653
|
+
perfr_scope PERFR_CONCAT(perfr_scope_, __LINE__) __attribute__((cleanup(perfr_scope_cleanup_), \
|
|
654
|
+
unused)) = perfr_start(PERFR_LIT(lit))
|
|
655
|
+
|
|
656
|
+
#endif /* __cplusplus / GNU C */
|
|
657
|
+
|
|
658
|
+
#if defined(_WIN32) && defined(_MSC_VER)
|
|
659
|
+
#pragma warning(pop)
|
|
660
|
+
#endif
|
|
661
|
+
|
|
662
|
+
#endif /* PERFR_API_H */
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: perfr
|
|
3
|
+
Version: 0.1.7
|
|
4
|
+
Summary: perfr: a low-overhead profiler. The capture service and web viewer in one command, plus the C/C++ and Python instrumentation API.
|
|
5
|
+
Author: The perfr Authors
|
|
6
|
+
License-Expression: BSD-2-Clause
|
|
7
|
+
Project-URL: Homepage, https://github.com/perfr/perfr
|
|
8
|
+
Project-URL: Source, https://github.com/perfr/perfr/tree/main/crates/perfr/python
|
|
9
|
+
Keywords: profiling,tracing,instrumentation,performance,perfr
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
13
|
+
Classifier: Operating System :: MacOS
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Software Development :: Debuggers
|
|
16
|
+
Classifier: Topic :: System :: Monitoring
|
|
17
|
+
Requires-Python: >=3.8
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
Requires-Dist: perfr-api==0.1.7
|
|
20
|
+
|
|
21
|
+
# perfr
|
|
22
|
+
|
|
23
|
+
perfr profiles a program that is already running. The service runs on Linux
|
|
24
|
+
and macOS, and the viewer is a web page. This package installs the build for
|
|
25
|
+
this machine with one command.
|
|
26
|
+
|
|
27
|
+
```console
|
|
28
|
+
$ pip install perfr
|
|
29
|
+
$ perfr
|
|
30
|
+
# then open http://127.0.0.1:44766/ in a browser
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The wheel carries a prebuilt, self-contained `perfr` binary (the
|
|
34
|
+
capture service, which also serves the viewer), the `libperfr`
|
|
35
|
+
instrumentation library and `perfr.h`, and depends on
|
|
36
|
+
[`perfr-api`](https://pypi.org/project/perfr-api/) so `import perfr_api` works
|
|
37
|
+
for instrumenting Python.
|
|
38
|
+
|
|
39
|
+
- `perfr ...` runs the bundled binary (also `python -m perfr`).
|
|
40
|
+
- `perfr.binary_path()`, `.library_path()`, `.header_path()` locate
|
|
41
|
+
the bundled files, e.g. to point a build system at `perfr.h`.
|
|
42
|
+
|
|
43
|
+
## What is in the wheel, and what is not
|
|
44
|
+
|
|
45
|
+
The Linux binary samples, records the scheduler, and hooks functions. The
|
|
46
|
+
macOS binary records manual scopes and Frida function hooks; sampling, the
|
|
47
|
+
scheduler, live disassembly, and auto-profiling are not in that build.
|
|
48
|
+
Manual instrumentation through the API (C, C++, Rust, Python) is in both.
|
|
49
|
+
Function hooks need `perfr-hook` beside `perfr`, and the `libperfr` in that
|
|
50
|
+
directory is also the agent it injects. The wheel includes both (see
|
|
51
|
+
`tools/release/build_wheels.sh`).
|
|
52
|
+
The console script marks `perfr-hook` executable, because a wheel
|
|
53
|
+
does not keep that bit. NVIDIA GPU lanes need `perfr-gpu` beside the
|
|
54
|
+
service; the release archive has it, this wheel does not.
|
|
55
|
+
|
|
56
|
+
Frida hooks do not need root on either OS. On macOS, attaching needs a
|
|
57
|
+
task port. On Linux, sampling needs `perf_event_paranoid` at 2 or below,
|
|
58
|
+
and the scheduler needs 0 or below. Root, `CAP_PERFMON`, or `CAP_SYS_ADMIN`
|
|
59
|
+
bypass that sysctl. Auto-profiling uses the kernel hook engine and needs
|
|
60
|
+
root or `CAP_SYS_ADMIN`. The `curl … | sh` installer
|
|
61
|
+
and the release archives are in [docs/releasing.md](../../../../docs/releasing.md).
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
perfr/__init__.py,sha256=vDX37zUXAzI4-_zWWftv_U3JnIvrw-3jPXp8-aPrN5A,2507
|
|
2
|
+
perfr/__main__.py,sha256=i35HYdtTX0Ow6OgWgZjP14hMZdsZ9ld80fH8nc2cv5A,275
|
|
3
|
+
perfr/libperfr.dll,sha256=758ftGOqMD8wdctSEC4tb0JDCELfe1QOkE97qp33ag0,3096064
|
|
4
|
+
perfr/perfr-hook.exe,sha256=I4qfhpxsXtCKGGJDaSWyQyPOeBL8ScJ23QEztCer7Zg,67910656
|
|
5
|
+
perfr/perfr.exe,sha256=Y0YpktyFjTEolqi-bHqh6s4njNdxvnKdj7W1wJTSVtI,22652416
|
|
6
|
+
perfr/perfr.h,sha256=IPoI_xKuvRfep7wgGxxVZBtod2qZDpOiWxMP7FU_4OE,27153
|
|
7
|
+
perfr/licenses/frida-core.txt,sha256=gDuLWqQVEDAiGzw_caZF2mJBk4Qh5JkBREp55cynX6g,2466
|
|
8
|
+
perfr/licenses/frida-gum.txt,sha256=tIU2qUO1qhdc6br84kiot4bKvQENevPTXWeEiLX1fSo,5814
|
|
9
|
+
perfr-0.1.7.dist-info/METADATA,sha256=fY8x-8Rojc7ElWxsIGvcxthLJ05B2jSaXDhC2RRQfGQ,2832
|
|
10
|
+
perfr-0.1.7.dist-info/WHEEL,sha256=bhMFZwp6VMtrbl2Ck6PlXryKaCggO1NzYn_HcFbBF1I,97
|
|
11
|
+
perfr-0.1.7.dist-info/entry_points.txt,sha256=LBj5lm6epN0zmLAHQULwh8Mf9VNMySGqQqlYMYoG5po,37
|
|
12
|
+
perfr-0.1.7.dist-info/top_level.txt,sha256=SgIjBNgEow0BfnTRlfI6r4A7rjl-eIexEiXjDMV9GaY,6
|
|
13
|
+
perfr-0.1.7.dist-info/RECORD,,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
perfr
|