includes/libs/Timing.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 /**
  22  * An interface to help developers measure the performance of their applications.
  23  * This interface closely matches the W3C's User Timing specification.
  24  * The key differences are:
  25  *
  26  * - The reference point for all measurements which do not explicitly specify
  27  *   a start time is $_SERVER['REQUEST_TIME_FLOAT'], not navigationStart.
  28  * - Successive calls to mark() and measure() with the same entry name cause
  29  *   the previous entry to be overwritten. This ensures that there is a 1:1
  30  *   mapping between names and entries.
  31  * - Because there is a 1:1 mapping, instead of getEntriesByName(), we have
  32  *   getEntryByName().
  33  *
  34  * The in-line documentation incorporates content from the User Timing Specification
  35  * http://www.w3.org/TR/user-timing/
  36  * Copyright © 2013 World Wide Web Consortium, (MIT, ERCIM, Keio, Beihang).
  37  * http://www.w3.org/Consortium/Legal/2015/doc-license
  38  *
  39  * @since 1.27
  40  */
  41 class Timing {
  42
  43         /** @var array[] */
  44         private $entries = array();
  45
  46         public function __construct() {
  47                 $this->clearMarks();
  48         }
  49
  50         /**
  51          * Store a timestamp with the associated name (a "mark")
  52          *
  53          * @param string $markName The name associated with the timestamp.
  54          *  If there already exists an entry by that name, it is overwritten.
  55          * @return array The mark that has been created.
  56          */
  57         public function mark( $markName ) {
  58                 $this->entries[$markName] = array(
  59                         'name'      => $markName,
  60                         'entryType' => 'mark',
  61                         'startTime' => microtime( true ),
  62                         'duration'  => 0,
  63                 );
  64                 return $this->entries[$markName];
  65         }
  66
  67         /**
  68          * @param string $markName The name of the mark that should
  69          *  be cleared. If not specified, all marks will be cleared.
  70          */
  71         public function clearMarks( $markName = null ) {
  72                 if ( $markName !== null ) {
  73                         unset( $this->entries[$markName] );
  74                 } else {
  75                         $this->entries = array(
  76                                 'requestStart' => array(
  77                                         'name'      => 'requestStart',
  78                                         'entryType' => 'mark',
  79                                         'startTime' => isset( $_SERVER['REQUEST_TIME_FLOAT'] )
  80                                                 ? $_SERVER['REQUEST_TIME_FLOAT']
  81                                                 : $_SERVER['REQUEST_TIME'],
  82                                         'duration'  => 0,
  83                                 ),
  84                         );
  85                 }
  86         }
  87
  88         /**
  89          * This method stores the duration between two marks along with
  90          * the associated name (a "measure").
  91          *
  92          * If neither the startMark nor the endMark argument is specified,
  93          * measure() will store the duration from $_SERVER['REQUEST_TIME_FLOAT'] to
  94          * the current time.
  95          * If the startMark argument is specified, but the endMark argument is not
  96          * specified, measure() will store the duration from the most recent
  97          * occurrence of the start mark to the current time.
  98          * If both the startMark and endMark arguments are specified, measure()
  99          * will store the duration from the most recent occurrence of the start
 100          * mark to the most recent occurrence of the end mark.
 101          *
 102          * @param string $measureName
 103          * @param string $startMark
 104          * @param string $endMark
 105          * @return array The measure that has been created.
 106          */
 107         public function measure( $measureName, $startMark = 'requestStart', $endMark = null ) {
 108                 $start = $this->getEntryByName( $startMark );
 109                 $startTime = $start['startTime'];
 110
 111                 if ( $endMark ) {
 112                         $end = $this->getEntryByName( $endMark );
 113                         $endTime = $end['startTime'];
 114                 } else {
 115                         $endTime = microtime( true );
 116                 }
 117
 118                 $this->entries[$measureName] = array(
 119                         'name'      => $measureName,
 120                         'entryType' => 'measure',
 121                         'startTime' => $startTime,
 122                         'duration'  => $endTime - $startTime,
 123                 );
 124
 125                 return $this->entries[$measureName];
 126         }
 127
 128         /**
 129          * Sort entries in chronological order with respect to startTime.
 130          */
 131         private function sortEntries() {
 132                 uasort( $this->entries, function ( $a, $b ) {
 133                         return 10000 * ( $a['startTime'] - $b['startTime'] );
 134                 } );
 135         }
 136
 137         /**
 138          * @return array[] All entries in chronological order.
 139          */
 140         public function getEntries() {
 141                 $this->sortEntries();
 142                 return $this->entries;
 143         }
 144
 145         /**
 146          * @param string $entryType
 147          * @return array[] Entries (in chronological order) that have the same value
 148          *  for the entryType attribute as the $entryType parameter.
 149          */
 150         public function getEntriesByType( $entryType ) {
 151                 $this->sortEntries();
 152                 $entries = array();
 153                 foreach ( $this->entries as $entry ) {
 154                         if ( $entry['entryType'] === $entryType ) {
 155                                 $entries[] = $entry;
 156                         }
 157                 }
 158                 return $entries;
 159         }
 160
 161         /**
 162          * @param string $name
 163          * @return array|null Entry named $name or null if it does not exist.
 164          */
 165         public function getEntryByName( $name ) {
 166                 return isset( $this->entries[$name] ) ? $this->entries[$name] : null;
 167         }
 168 }