Skip to content

Commit 23190e2

Browse files
jbboehrjbboehr
committed
Update readme, add changelog and package.xml
1 parent 34e6e70 commit 23190e2

File tree

7 files changed

+178
-19
lines changed

7 files changed

+178
-19
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ nbproject
5151
run-tests.php
5252
.settings
5353
specs
54+
*-*.*.*.tgz
5455
test_coverage/
5556
test.php
5657
tests/**/*.diff

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Changelog
2+
3+
All Notable changes to `php-perfidious` will be documented in this file.
4+
5+
Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
6+
7+
## [Unreleased]
8+
9+
## 0.1.0 - 2024-04-07
10+
11+
### Added
12+
13+
- Initial release
14+
15+
[Unreleased]: https://github.com/jbboehr/php-perfidious/compare/v0.1.0...HEAD

‎README.md‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55
[![Codecov](https://codecov.io/gh/jbboehr/php-perfidious/graph/badge.svg?token=DSLDXIWHC5)](https://codecov.io/gh/jbboehr/php-perfidious)
66
[![Coveralls](https://coveralls.io/repos/github/jbboehr/php-perfidious/badge.svg?branch=master)](https://coveralls.io/github/jbboehr/php-perfidious?branch=master)
77
[![License: AGPL v3+](https://img.shields.io/badge/License-AGPL_v3%2b-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
8-
![stability-experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
98
![Language](https://img.shields.io/github/languages/top/jbboehr/php-perfidious)
109
![Tag](https://img.shields.io/github/v/tag/jbboehr/php-perfidious)
10+
![stability-experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
1111

1212
This extension provides access to the performance monitoring *counters* exposed
1313
by the Linux `perf_events` kernel API.
@@ -88,17 +88,24 @@ Or you can configure a global or per-request handle:
8888
// with the following INI settings:
8989
// perfidious.request.enable=1
9090
// perfidious.request.metrics=perf::PERF_COUNT_SW_CPU_CLOCK:u,perf::PERF_COUNT_SW_PAGE_FAULTS:u,perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u
91-
var_dump(Perfidious\request_handle()?->readArray());
91+
var_dump(Perfidious\request_handle()?->read());
9292
```
9393

9494
```text
95-
array(3) {
96-
["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
97-
int(120880)
98-
["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
99-
int(64)
100-
["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
101-
int(0)
95+
object(Perfidious\ReadResult)#%d (%d) {
96+
["timeEnabled"]=>
97+
int(260840)
98+
["timeRunning"]=>
99+
int(260840)
100+
["values"]=>
101+
array(3) {
102+
["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
103+
int(142740)
104+
["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
105+
int(64)
106+
["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
107+
int(0)
108+
}
102109
}
103110
```
104111

@@ -118,9 +125,9 @@ Some notable generic perf events are:
118125

119126
| Name | Default | Changeable | Description |
120127
| --------------------- | -------- | ----------- | ------------ |
121-
| `perfidious.overflow_mode` | `0` | `PHP_INI_SYSTEM` | Sets the overflow behavior when casting counters from `uint64_t` to `zend_long`. See the constants `Perfidious\OVERFLOW_*` for other values. Note that when set to `Perfidious\OVERFLOW_WARN`, `read` and `readArray` may return `NULL`, despite their type signatures indicating otherwise. |
122128
| `perfidious.global.enable` | `0` | `PHP_INI_SYSTEM` | Set to `1` to enable the global handle. This handle is kept open between requests. You can read from this handle via e.g. `var_dump(Perfidious\global_handle()?->read());`. |
123129
| `perfidious.global.metrics` | `perf::PERF_COUNT_HW_CPU_CYCLES:u`, `perf::PERF_COUNT_HW_INSTRUCTIONS:u` | `PHP_INI_SYSTEM` | The metrics to monitor with the global handle. |
130+
| `perfidious.overflow_mode` | `0` | `PHP_INI_SYSTEM` | Sets the overflow behavior when casting counters from `uint64_t` to `zend_long`. See the constants `Perfidious\OVERFLOW_*` for other values. Note that when set to `Perfidious\OVERFLOW_WARN`, `read` and `readArray` may return `NULL`, despite their type signatures indicating otherwise. |
124131
| `perfidious.request.enable` | `0` | `PHP_INI_SYSTEM` | Set to `1` to enable the per-request handle. This handle is kept open between requests, but reset before and after. You can read from this handle via e.g. `var_dump(Perfidious\request_handle()?->read());` |
125132
| `perfidious.request.metrics` | `perf::PERF_COUNT_HW_CPU_CYCLES:u`, `perf::PERF_COUNT_HW_INSTRUCTIONS:u` | `PHP_INI_SYSTEM` | The metrics to monitor with the request handle. |
126133

‎examples/three-sw-clock.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,6 @@
66
$handle->enable();
77

88
for ($i = 0; $i < 3; $i++) {
9-
var_dump($handle->readArray());
9+
var_dump($handle->read());
1010
sleep(1);
1111
}

‎examples/watch.php‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,6 @@
3838
$stats = $handle->read();
3939
$percent_running = $stats->timeEnabled > 0 ? 100 * $stats->timeRunning / $stats->timeEnabled : 0;
4040

41-
//\PHPStan\dumpType($stats);
42-
4341
printf("cpu=%d pid=%d\n", $cpu, $pid);
4442
printf("time_enabled=%d time_running=%d percent_running=%d%%\n", $stats->timeEnabled, $stats->timeRunning, $percent_running);
4543
foreach ($stats->values as $k => $v) {

‎package.xml‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<package packagerversion="1.10.1" version="2.0" xmlns="http://pear.php.net/dtd/package-2.0" xmlns:tasks="http://pear.php.net/dtd/tasks-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0 http://pear.php.net/dtd/tasks-1.0.xsd http://pear.php.net/dtd/package-2.0 http://pear.php.net/dtd/package-2.0.xsd">
3+
<name>perfidious</name>
4+
<channel>pecl.php.net</channel>
5+
<summary>Access perf_events PMU counters</summary>
6+
<description>This extension provides access to the performance monitoring counters exposed by the Linux perf_events kernel API.</description>
7+
<lead>
8+
<name>John Boehr</name>
9+
<user>jbboehr</user>
10+
<email>jbboehr@gmail.com</email>
11+
<active>yes</active>
12+
</lead>
13+
<date>2024-04-07</date>
14+
<version>
15+
<release>0.1.0</release>
16+
<api>0.1.0</api>
17+
</version>
18+
<stability>
19+
<release>beta</release>
20+
<api>beta</api>
21+
</stability>
22+
<license uri="https://www.gnu.org/licenses/agpl-3.0.en.html">AGPL-3.0-or-later</license>
23+
<notes>
24+
- Initial release
25+
</notes>
26+
<contents>
27+
<dir name="/">
28+
<file name="CHANGELOG.md" role="doc" />
29+
<file name="LICENSE.md" role="doc" />
30+
<file name="README.md" role="doc" />
31+
<file name="config.m4" role="src" />
32+
33+
<file name="php_perfidious.h" role="src" />
34+
<file name="src/private.h" role="src" />
35+
<file name="src/handle.h" role="src" />
36+
<file name="src/read_result.c" role="src" />
37+
<file name="src/handle.c" role="src" />
38+
<file name="src/functions.c" role="src" />
39+
<file name="src/exceptions.c" role="src" />
40+
<file name="src/pmu_info.c" role="src" />
41+
<file name="src/extension.c" role="src" />
42+
<file name="src/pmu_event_info.c" role="src" />
43+
44+
<file name="examples/sieve2.php" role="doc" />
45+
<file name="examples/watch.php" role="doc" />
46+
<file name="examples/all-events.php" role="doc" />
47+
<file name="examples/memory.php" role="doc" />
48+
<file name="examples/three-sw-clock.php" role="doc" />
49+
<file name="examples/estimate-overhead.php" role="doc" />
50+
<file name="examples/sieve.php" role="doc" />
51+
52+
<file name="m4/ax_compiler_flags_cxxflags.m4" role="src" />
53+
<file name="m4/ax_compiler_flags.m4" role="src" />
54+
<file name="m4/ax_require_defined.m4" role="src" />
55+
<file name="m4/ax_compiler_flags_ldflags.m4" role="src" />
56+
<file name="m4/ax_is_release.m4" role="src" />
57+
<file name="m4/ax_compiler_flags_cflags.m4" role="src" />
58+
<file name="m4/ax_compiler_vendor.m4" role="src" />
59+
<file name="m4/ax_check_link_flag.m4" role="src" />
60+
<file name="m4/ax_append_flag.m4" role="src" />
61+
<file name="m4/ax_append_link_flags.m4" role="src" />
62+
<file name="m4/ax_append_compile_flags.m4" role="src" />
63+
<file name="m4/ax_prepend_flag.m4" role="src" />
64+
<file name="m4/ax_cflags_warn_all.m4" role="src" />
65+
<file name="m4/ax_compiler_flags_gir.m4" role="src" />
66+
67+
<file name="tests/info-request-closed.phpt" role="test" />
68+
<file name="tests/info-request.phpt" role="test" />
69+
<file name="tests/info-request-invalid.phpt" role="test" />
70+
<file name="tests/get-pmu-info.phpt" role="test" />
71+
<file name="tests/global-handle/enabled.phpt" role="test" />
72+
<file name="tests/global-handle/stays-open.phpt" role="test" />
73+
<file name="tests/global-handle/disabled.phpt" role="test" />
74+
<file name="tests/open.phpt" role="test" />
75+
<file name="tests/list-pmu-events.phpt" role="test" />
76+
<file name="tests/get-pmu-event-info.phpt" role="test" />
77+
<file name="tests/list-pmu-events-unknown-pmu.phpt" role="test" />
78+
<file name="tests/handle/debug-corrupt-metric-ids.phpt" role="test" />
79+
<file name="tests/handle/dirty-3.phpt" role="test" />
80+
<file name="tests/handle/zero-after-reset.phpt" role="test" />
81+
<file name="tests/handle/open-fails-missing-cap-debug.phpt" role="test" />
82+
<file name="tests/handle/open-fails-non-string-event.phpt" role="test" />
83+
<file name="tests/handle/non-zero-after-enable.phpt" role="test" />
84+
<file name="tests/handle/raw-stream.phpt" role="test" />
85+
<file name="tests/handle/dirty.phpt" role="test" />
86+
<file name="tests/handle/sequential-reads.phpt" role="test" />
87+
<file name="tests/handle/read.phpt" role="test" />
88+
<file name="tests/handle/invalid-event-name-2.phpt" role="test" />
89+
<file name="tests/handle/raw-stream-invalid-idx.phpt" role="test" />
90+
<file name="tests/handle/open-fails-invalid-pid.phpt" role="test" />
91+
<file name="tests/handle/disable.phpt" role="test" />
92+
<file name="tests/handle/invalid-event-name.phpt" role="test" />
93+
<file name="tests/handle/enable.phpt" role="test" />
94+
<file name="tests/handle/dirty-4.phpt" role="test" />
95+
<file name="tests/handle/open-fails-invalid-cpu.phpt" role="test" />
96+
<file name="tests/handle/open-fails-missing-cap.phpt" role="test" />
97+
<file name="tests/handle/reset.phpt" role="test" />
98+
<file name="tests/handle/dirty-2.phpt" role="test" />
99+
<file name="tests/info-global.phpt" role="test" />
100+
<file name="tests/request-handle/enabled.phpt" role="test" />
101+
<file name="tests/request-handle/stays-open.phpt" role="test" />
102+
<file name="tests/request-handle/disabled.phpt" role="test" />
103+
<file name="tests/info-global-closed.phpt" role="test" />
104+
<file name="tests/list-pmus.phpt" role="test" />
105+
<file name="tests/info-both.phpt" role="test" />
106+
<file name="tests/info.phpt" role="test" />
107+
<file name="tests/info-global-invalid.phpt" role="test" />
108+
<file name="tests/overflow/throw.phpt" role="test" />
109+
<file name="tests/overflow/whoops.phpt" role="test" />
110+
<file name="tests/overflow/saturate.phpt" role="test" />
111+
<file name="tests/overflow/warn.phpt" role="test" />
112+
<file name="tests/overflow/wrap.phpt" role="test" />
113+
<file name="tests/version.phpt" role="test" />
114+
</dir>
115+
</contents>
116+
<dependencies>
117+
<required>
118+
<php>
119+
<min>7.2.0</min>
120+
</php>
121+
<pearinstaller>
122+
<min>1.4.1</min>
123+
</pearinstaller>
124+
<extension>
125+
<name>spl</name>
126+
</extension>
127+
</required>
128+
</dependencies>
129+
<providesextension>perfidious</providesextension>
130+
<extsrcrelease />
131+
</package>

‎tests/request-handle/enabled.phpt‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,21 @@ perfidious.request.metrics=perf::PERF_COUNT_SW_CPU_CLOCK:u,perf::PERF_COUNT_SW_P
99
<?php
1010
$handle = Perfidious\request_handle();
1111
var_dump(get_class($handle));
12-
var_dump($handle->readArray());
12+
var_dump($handle->read());
1313
--EXPECTF--
1414
string(%d) "Perfidious\Handle"
15-
array(3) {
16-
["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
15+
object(Perfidious\ReadResult)#%d (%d) {
16+
["timeEnabled"]=>
1717
int(%d)
18-
["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
19-
int(%d)
20-
["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
18+
["timeRunning"]=>
2119
int(%d)
20+
["values"]=>
21+
array(%d) {
22+
["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
23+
int(%d)
24+
["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
25+
int(%d)
26+
["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
27+
int(%d)
28+
}
2229
}

0 commit comments

Comments
 (0)