Profiling
=========

Usage
-----

To enjoy the profiling support in your module, all you have to do is to call 
profiling_start('some identifier') function at the point you want to start a
timer, then call profiling_stop('some identifer') were you want to stop it.

If you aptempt to start the same timer twice on the same HTTP request, log
messages will arrive in watchdog. The same behavior apply if you aptempt to
stop the same timer twice.

Important notice
----------------

Even if profiling is disabled or suspended (see the admin page exclusion or
the admin page default suspend mode for example), the functions must be present,
but empty. Don't attempt to check any variable to ensure the module is enabled 
or disabled, even if disable empty functions will be there therefore ensuring 
minimal impact.

Do not use the OOP API directly, if the module is disabled and you call the OOP
API you will uselessly initialize the backend singleton, which would have small
but existing performance overhead.

Notes for developers
--------------------

Because you might want to avoid massive if (module_exists('profiling') and
keep a permanent profiling support, you can safely add, at the very beginning
of your .module files the following code:

<?php
// Profiling module integration.
if (!function_exists('profiling_start')) {
  function profiling_start() { }
  function profiling_stop() { }
}
?>

This will create foo functions that will be used instead the profiling module
ones. This is safe because the profiling module implements the hook_boot(),
which makes it very own .module file loaded before any others, even with an
higher weight.

Some rare exceptions exists, like the purl module, which uses themselves the
hook_boot() hook, in this particular case you might want to lower profiling
module weight so its own .module file will be loaded before others.

This module does not do any heavy Drupal tricks and does not depend on any
other module, so you can afford setting a really low weight for it.

Using this methodology will ensure that if profiling module is disabled, your
module won't crash and profiling module calls won't hurt performances at all
(except the cost of void functions call, which is not quite a problem when
you consider it).

Or!
---

If you don't want to use above methodology, because you don't like it, you
could just write proxy functions, as such:

<?php
// Profiling module integration.
function mymodule_profiling_start($name, $collection = NULL) {
  static $profiling_enabled;
  if (!isset($profiling_enabled)) {
    $profiling_enabled = module_exists('profiling');
  }
  if ($profiling_enabled) {
    profiling_start($name, $collection);
  }
}
?>

This will have a bigger impact on performances.
