<commit_before># POSIX Clocks for PHP

This project provides an interface to the real-time, monotonic, CPU-time,
and various other clocks available on systems that implement the POSIX.1b
standard (e.g., Linux, BSD, Solaris, OS X, etc)

#### How is this an improvement on the `microtime()` built-in?

Using microtime is perfectly fine if you need a timestamp and can live with
microsecond resolution. The problem arises when you need to accurately measure
differences (deltas) in time, especially over relatively long periods.
Say, for example, you need to measure the amount of time a large script takes
to execute.

The `microtime()` PHP function relies on the `gettimeofday(2)` system call,
which is quite useful for pinpointing a certain moment in Earthling history.
But, if this realtime system clock is adjusted (maybe by [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol),
or maybe by your friendly neighborhood sysadmin) while you're trying
to *measure time*...well, [you're gonna have a bad...you catch the drift](http://blog.habets.pp.se/2010/09/gettimeofday-should-never-be-used-to-measure-time).

In this case you need access to your system's _monotonic_ clock, or better yet,
its *raw* monotonic clock, if available.

This extension provides access to **all** the clocks supported by your system,
often with nanosecond resolution. See below for a list of common clocks
and their PHP constants.


<br>
## Installation
---

```
git clone https://github.com/adrianguenter/php-posix-clocks.git
cd php-posix-clocks
phpize
./configure
make && make test
sudo make install
```

##### Enabling on Debian/Ubuntu:
```
sudo cp posixclocks.deb.ini /etc/php5/mods-available/posixclocks.ini
sudo php5enmod posixclocks
```

##### Enabling everywhere else:
Add the line `extension=posixclocks.so` to your php.ini


<br>
<a name="interface"/>
## Interface
---

<a name="interface-clock_gettime"/>
### posix_clock_gettime

<a name="interface-clock_gettime-desc"/>
**-- Description --**

`mixed` **`posix_clock_gettime`** ( [<br>
&nbsp;&nbsp;`int` **`$clock_id = PSXCLK_CLOCK_REALTIME`** ,<br>
&nbsp;&nbsp;`int` **`$return_as = PSXCLK_AS_STRING`** ,<br>
&nbsp;&nbsp;`bool` **`round_to_res = false`**<br>
] )

Provides an interface to [`clock_gettime(2)`](http://man7.org/linux/man-pages/man2/clock_gettime.2.html).

<br>
<a name="interface-clock_gettime-params"/>
**-- Parameters --**

**_clock_id_** The clock to retrieve; defaults to `PSXCLK_CLOCK_REALTIME` if not provided.

**_return_as_** Defines the return value type as detailed in the [return values](#interface-clock_gettime-retvals)
section below. Defaults to `PSXCLK_AS_STRING`; other valid values are
`PSXCLK_AS_FLOAT` and `PSXCLK_AS_TIMESPEC`.

**_round_to_res_** Whether or not to round down (floor) the clock's value to the
nearest multiple of its resolution. Defaults to `false`.

<br>
<a name="interface-clock_gettime-retvals"/>
**-- Return Values --**

**`string`** By default (`return_as` = `PSXCLK_AS_STRING`) a string representing
the decimal value of the requested clock is returned.

**`float`** If `return_as` = `PSXCLK_AS_FLOAT`, a float (double) representing
the decimal value of the requested clock is returned.
_**WARNING:** The floating point type is likely not large enough to represent
certain time values or accurate to the last digit!_

**`object`**  If `return_as` = `PSXCLK_AS_TIMESPEC`, an object of class
`stdClass` representing the underlying C data structure ([`struct timespec`](http://pubs.opengroup.org/onlinepubs/7908799/xsh/time.h.html))
is returned.

```
stdClass Object {
   string|int tv_sec       Seconds (as string if value overflows integer)
          int tv_nsec      Nanoseconds<commit_msg>Reword "apply resolution" to "round to resolution"<commit_after># POSIX Clocks for PHP

This project provides an interface to the real-time, monotonic, CPU-time,
and various other clocks available on systems that implement the POSIX.1b
standard (e.g., Linux, BSD, Solaris, OS X, etc)

#### How is this an improvement on the `microtime()` built-in?

Using microtime is perfectly fine if you need a timestamp and can live with
microsecond resolution. The problem arises when you need to accurately measure
differences (deltas) in time, especially over relatively long periods.
Say, for example, you need to measure the amount of time a large script takes
to execute.

The `microtime()` PHP function relies on the `gettimeofday(2)` system call,
which is quite useful for pinpointing a certain moment in Earthling history.
But, if this realtime system clock is adjusted (maybe by [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol),
or maybe by your friendly neighborhood sysadmin) while you're trying
to *measure time*...well, [you're gonna have a bad...you catch the drift](http://blog.habets.pp.se/2010/09/gettimeofday-should-never-be-used-to-measure-time).

In this case you need access to your system's _monotonic_ clock, or better yet,
its *raw* monotonic clock, if available.

This extension provides access to **all** the clocks supported by your system,
often with nanosecond resolution. See below for a list of common clocks
and their PHP constants.


<br>
## Installation
---

```
git clone https://github.com/adrianguenter/php-posix-clocks.git
cd php-posix-clocks
phpize
./configure
make && make test
sudo make install
```

##### Enabling on Debian/Ubuntu:
```
sudo cp posixclocks.deb.ini /etc/php5/mods-available/posixclocks.ini
sudo php5enmod posixclocks
```

##### Enabling everywhere else:
Add the line `extension=posixclocks.so` to your php.ini


<br>
<a name="interface"/>
## Interface
---

<a name="interface-clock_gettime"/>
### posix_clock_gettime

<a name="interface-clock_gettime-desc"/>
**-- Description --**

`mixed` **`posix_clock_gettime`** ( [<br>
&nbsp;&nbsp;`int` **`$clock_id = PSXCLK_CLOCK_REALTIME`** ,<br>
&nbsp;&nbsp;`int` **`$return_as = PSXCLK_AS_STRING`** ,<br>
&nbsp;&nbsp;`bool` **`round_to_res = false`**<br>
] )

Provides an interface to [`clock_gettime(2)`](http://man7.org/linux/man-pages/man2/clock_gettime.2.html).

<br>
<a name="interface-clock_gettime-params"/>
**-- Parameters --**

**_clock_id_** The clock to retrieve; defaults to `PSXCLK_CLOCK_REALTIME` if not provided.

**_return_as_** Defines the return value type as detailed in the [return values](#interface-clock_gettime-retvals)
section below. Defaults to `PSXCLK_AS_STRING`; other valid values are
`PSXCLK_AS_FLOAT` and `PSXCLK_AS_TIMESPEC`.

**_round_to_res_** Whether or not to round down (floor) the clock's value to the
nearest multiple of its resolution. Defaults to `false`.

<br>
<a name="interface-clock_gettime-retvals"/>
**-- Return Values --**

**`string`** By default (`return_as` = `PSXCLK_AS_STRING`) a string representing
the decimal value of the requested clock is returned.

**`float`** If `return_as` = `PSXCLK_AS_FLOAT`, a float (double) representing
the decimal value of the requested clock is returned.

_**WARNING:** The floating point type is likely not large enough to represent
certain time values or accurate to the last digit!_

**`object`**  If `return_as` = `PSXCLK_AS_TIMESPEC`, an object of class
`stdClass` representing the underlying C data structure ([`struct timespec`](http://pubs.opengroup.org/onlinepubs/7908799/xsh/time.h.html))
is returned.

```
stdClass Object {
   string|int tv_sec       Seconds (as string if value overflows integer)
          int tv_nsec      Nanoseconds
{'fraction_non_alphanumeric': 0.11937483158178389, 'fraction_numerical': 0.005658852061438965, 'mean_word_length': 4.967041800643087, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 29, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3646729', 'n_tokens_mistral': 2430, 'n_tokens_neox': 2286, 'n_words': 833}