Update readme, add changelog and package.xml

jbboehr · Apr 7, 2024 · 23190e2 · 23190e2
1 parent 34e6e70
commit 23190e2
Show file tree

Hide file tree

Showing 7 changed files with 178 additions and 19 deletions.
diff --git a/.gitignore b/.gitignore
@@ -51,6 +51,7 @@ nbproject
 run-tests.php
 .settings
 specs
+*-*.*.*.tgz
 test_coverage/
 test.php
 tests/**/*.diff

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,15 @@
+# Changelog
+
+All Notable changes to `php-perfidious` will be documented in this file.
+
+Updates should follow the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
+
+## [Unreleased]
+
+## 0.1.0 - 2024-04-07
+
+### Added
+
+- Initial release
+
+[Unreleased]: https://github.com/jbboehr/php-perfidious/compare/v0.1.0...HEAD
diff --git a/README.md b/README.md
@@ -5,9 +5,9 @@
 [![Codecov](https://codecov.io/gh/jbboehr/php-perfidious/graph/badge.svg?token=DSLDXIWHC5)](https://codecov.io/gh/jbboehr/php-perfidious)
 [![Coveralls](https://coveralls.io/repos/github/jbboehr/php-perfidious/badge.svg?branch=master)](https://coveralls.io/github/jbboehr/php-perfidious?branch=master)
 [![License: AGPL v3+](https://img.shields.io/badge/License-AGPL_v3%2b-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
-![stability-experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
 ![Language](https://img.shields.io/github/languages/top/jbboehr/php-perfidious)
 ![Tag](https://img.shields.io/github/v/tag/jbboehr/php-perfidious)
+![stability-experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
 
 This extension provides access to the performance monitoring *counters* exposed
 by the Linux `perf_events` kernel API.
@@ -88,17 +88,24 @@ Or you can configure a global or per-request handle:
 // with the following INI settings:
 // perfidious.request.enable=1
 // perfidious.request.metrics=perf::PERF_COUNT_SW_CPU_CLOCK:u,perf::PERF_COUNT_SW_PAGE_FAULTS:u,perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u
-var_dump(Perfidious\request_handle()?->readArray());
+var_dump(Perfidious\request_handle()?->read());
 ```
 
 ```text
-array(3) {
-  ["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
-  int(120880)
-  ["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
-  int(64)
-  ["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
-  int(0)
+object(Perfidious\ReadResult)#%d (%d) {
+  ["timeEnabled"]=>
+  int(260840)
+  ["timeRunning"]=>
+  int(260840)
+  ["values"]=>
+  array(3) {
+    ["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
+    int(142740)
+    ["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
+    int(64)
+    ["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
+    int(0)
+  }
 }
 ```
 
@@ -118,9 +125,9 @@ Some notable generic perf events are:
 
 | Name | Default | Changeable | Description  |
 | --------------------- | -------- | ----------- | ------------ |
-| `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. |
 | `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());`. |
 | `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. |
+| `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. |
 | `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());` |
 | `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. |
 

diff --git a/examples/three-sw-clock.php b/examples/three-sw-clock.php
@@ -6,6 +6,6 @@
 $handle->enable();
 
 for ($i = 0; $i < 3; $i++) {
-    var_dump($handle->readArray());
+    var_dump($handle->read());
     sleep(1);
 }
diff --git a/examples/watch.php b/examples/watch.php
@@ -38,8 +38,6 @@
     $stats = $handle->read();
     $percent_running = $stats->timeEnabled > 0 ? 100 * $stats->timeRunning / $stats->timeEnabled : 0;
 
-    //\PHPStan\dumpType($stats);
-
     printf("cpu=%d pid=%d\n", $cpu, $pid);
     printf("time_enabled=%d time_running=%d percent_running=%d%%\n", $stats->timeEnabled, $stats->timeRunning, $percent_running);
     foreach ($stats->values as $k => $v) {

diff --git a/package.xml b/package.xml
@@ -0,0 +1,131 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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">
+ <name>perfidious</name>
+ <channel>pecl.php.net</channel>
+ <summary>Access perf_events PMU counters</summary>
+ <description>This extension provides access to the performance monitoring counters exposed by the Linux perf_events kernel API.</description>
+ <lead>
+  <name>John Boehr</name>
+  <user>jbboehr</user>
+  <email>jbboehr@gmail.com</email>
+  <active>yes</active>
+ </lead>
+ <date>2024-04-07</date>
+ <version>
+  <release>0.1.0</release>
+  <api>0.1.0</api>
+ </version>
+ <stability>
+  <release>beta</release>
+  <api>beta</api>
+ </stability>
+ <license uri="https://www.gnu.org/licenses/agpl-3.0.en.html">AGPL-3.0-or-later</license>
+ <notes>
+  - Initial release
+ </notes>
+ <contents>
+  <dir name="/">
+   <file name="CHANGELOG.md" role="doc" />
+   <file name="LICENSE.md" role="doc" />
+   <file name="README.md" role="doc" />
+   <file name="config.m4" role="src" />
+
+   <file name="php_perfidious.h" role="src" />
+   <file name="src/private.h" role="src" />
+   <file name="src/handle.h" role="src" />
+   <file name="src/read_result.c" role="src" />
+   <file name="src/handle.c" role="src" />
+   <file name="src/functions.c" role="src" />
+   <file name="src/exceptions.c" role="src" />
+   <file name="src/pmu_info.c" role="src" />
+   <file name="src/extension.c" role="src" />
+   <file name="src/pmu_event_info.c" role="src" />
+
+   <file name="examples/sieve2.php" role="doc" />
+   <file name="examples/watch.php" role="doc" />
+   <file name="examples/all-events.php" role="doc" />
+   <file name="examples/memory.php" role="doc" />
+   <file name="examples/three-sw-clock.php" role="doc" />
+   <file name="examples/estimate-overhead.php" role="doc" />
+   <file name="examples/sieve.php" role="doc" />
+
+   <file name="m4/ax_compiler_flags_cxxflags.m4" role="src" />
+   <file name="m4/ax_compiler_flags.m4" role="src" />
+   <file name="m4/ax_require_defined.m4" role="src" />
+   <file name="m4/ax_compiler_flags_ldflags.m4" role="src" />
+   <file name="m4/ax_is_release.m4" role="src" />
+   <file name="m4/ax_compiler_flags_cflags.m4" role="src" />
+   <file name="m4/ax_compiler_vendor.m4" role="src" />
+   <file name="m4/ax_check_link_flag.m4" role="src" />
+   <file name="m4/ax_append_flag.m4" role="src" />
+   <file name="m4/ax_append_link_flags.m4" role="src" />
+   <file name="m4/ax_append_compile_flags.m4" role="src" />
+   <file name="m4/ax_prepend_flag.m4" role="src" />
+   <file name="m4/ax_cflags_warn_all.m4" role="src" />
+   <file name="m4/ax_compiler_flags_gir.m4" role="src" />
+
+   <file name="tests/info-request-closed.phpt" role="test" />
+   <file name="tests/info-request.phpt" role="test" />
+   <file name="tests/info-request-invalid.phpt" role="test" />
+   <file name="tests/get-pmu-info.phpt" role="test" />
+   <file name="tests/global-handle/enabled.phpt" role="test" />
+   <file name="tests/global-handle/stays-open.phpt" role="test" />
+   <file name="tests/global-handle/disabled.phpt" role="test" />
+   <file name="tests/open.phpt" role="test" />
+   <file name="tests/list-pmu-events.phpt" role="test" />
+   <file name="tests/get-pmu-event-info.phpt" role="test" />
+   <file name="tests/list-pmu-events-unknown-pmu.phpt" role="test" />
+   <file name="tests/handle/debug-corrupt-metric-ids.phpt" role="test" />
+   <file name="tests/handle/dirty-3.phpt" role="test" />
+   <file name="tests/handle/zero-after-reset.phpt" role="test" />
+   <file name="tests/handle/open-fails-missing-cap-debug.phpt" role="test" />
+   <file name="tests/handle/open-fails-non-string-event.phpt" role="test" />
+   <file name="tests/handle/non-zero-after-enable.phpt" role="test" />
+   <file name="tests/handle/raw-stream.phpt" role="test" />
+   <file name="tests/handle/dirty.phpt" role="test" />
+   <file name="tests/handle/sequential-reads.phpt" role="test" />
+   <file name="tests/handle/read.phpt" role="test" />
+   <file name="tests/handle/invalid-event-name-2.phpt" role="test" />
+   <file name="tests/handle/raw-stream-invalid-idx.phpt" role="test" />
+   <file name="tests/handle/open-fails-invalid-pid.phpt" role="test" />
+   <file name="tests/handle/disable.phpt" role="test" />
+   <file name="tests/handle/invalid-event-name.phpt" role="test" />
+   <file name="tests/handle/enable.phpt" role="test" />
+   <file name="tests/handle/dirty-4.phpt" role="test" />
+   <file name="tests/handle/open-fails-invalid-cpu.phpt" role="test" />
+   <file name="tests/handle/open-fails-missing-cap.phpt" role="test" />
+   <file name="tests/handle/reset.phpt" role="test" />
+   <file name="tests/handle/dirty-2.phpt" role="test" />
+   <file name="tests/info-global.phpt" role="test" />
+   <file name="tests/request-handle/enabled.phpt" role="test" />
+   <file name="tests/request-handle/stays-open.phpt" role="test" />
+   <file name="tests/request-handle/disabled.phpt" role="test" />
+   <file name="tests/info-global-closed.phpt" role="test" />
+   <file name="tests/list-pmus.phpt" role="test" />
+   <file name="tests/info-both.phpt" role="test" />
+   <file name="tests/info.phpt" role="test" />
+   <file name="tests/info-global-invalid.phpt" role="test" />
+   <file name="tests/overflow/throw.phpt" role="test" />
+   <file name="tests/overflow/whoops.phpt" role="test" />
+   <file name="tests/overflow/saturate.phpt" role="test" />
+   <file name="tests/overflow/warn.phpt" role="test" />
+   <file name="tests/overflow/wrap.phpt" role="test" />
+   <file name="tests/version.phpt" role="test" />
+  </dir>
+ </contents>
+ <dependencies>
+  <required>
+   <php>
+    <min>7.2.0</min>
+   </php>
+   <pearinstaller>
+    <min>1.4.1</min>
+   </pearinstaller>
+   <extension>
+    <name>spl</name>
+   </extension>
+  </required>
+ </dependencies>
+ <providesextension>perfidious</providesextension>
+ <extsrcrelease />
+</package>
diff --git a/tests/request-handle/enabled.phpt b/tests/request-handle/enabled.phpt
@@ -9,14 +9,21 @@ perfidious.request.metrics=perf::PERF_COUNT_SW_CPU_CLOCK:u,perf::PERF_COUNT_SW_P
 <?php
 $handle = Perfidious\request_handle();
 var_dump(get_class($handle));
-var_dump($handle->readArray());
+var_dump($handle->read());
 --EXPECTF--
 string(%d) "Perfidious\Handle"
-array(3) {
-  ["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
+object(Perfidious\ReadResult)#%d (%d) {
+  ["timeEnabled"]=>
   int(%d)
-  ["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
-  int(%d)
-  ["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
+  ["timeRunning"]=>
   int(%d)
+  ["values"]=>
+  array(%d) {
+    ["perf::PERF_COUNT_SW_CPU_CLOCK:u"]=>
+    int(%d)
+    ["perf::PERF_COUNT_SW_PAGE_FAULTS:u"]=>
+    int(%d)
+    ["perf::PERF_COUNT_SW_CONTEXT_SWITCHES:u"]=>
+    int(%d)
+  }
 }