# NAME

Catalyst::Plugin::MemoryUsage - Profile memory usage of requests

# VERSION

version 0.3.0

# SYNOPSIS

In YourApp.pm:

    package YourApp;

    use Catalyst qw/
        MemoryUsage
    /;

In a Controller class:

    sub foo :Path( '/foo' ) {
         # ...
         

         something_big_and_scary();
         

         $c->memory_usage->record( 'finished running iffy code' );
         

         # ...
    }

In yourapp.conf:

    <Plugin::MemoryUsage>
        report            1
        action_milestones 1
    </Plugin::MemoryUsage>

# DESCRIPTION

`Catalyst::Plugin::MemoryUsage` adds a memory usage profile to your debugging
log, which looks like this:   

 [debug] memory usage of request
 .--------------------------------------------------+------+------+------+------+------+------+------+------+------+------.
 |                                                  | vsz  | del- | rss  | del- | sha- | del- | code | del- | data | del- |
 |                                                  |      | ta   |      | ta   | red  | ta   |      | ta   |      | ta   |
 +--------------------------------------------------+------+------+------+------+------+------+------+------+------+------+
 | preparing for the request                        | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 | after TestApp::Controller::Root : root/_BEGIN    | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 | after TestApp::Controller::Root : root/_AUTO     | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 | in the middle of index                           | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 | after TestApp::Controller::Root : root/index     | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 | after TestApp::Controller::Root : root/_ACTION   | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 | after TestApp::Controller::Root : root/_END      | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 | after TestApp::Controller::Root : root/_DISPATCH | 28M  |      | 22M  |      | 2.2M |      | 1.1M |      | 20M  |      |
 '--------------------------------------------------+------+------+------+------+------+------+------+------+------+------'  

# CONFIGURATION

## report

If true, the memory usage is reported automatically (at debug level)
at the end of the request.  

Defaults to true if we are in debugging mode,
false otherwise.

## action_milestones

If true, automatically adds milestones for each action, as seen in the
DESCRIPTION.  

Defaults to true if we are in debugging mode,
false otherwise.

# METHODS

## `memory_usage()`

Returns the [Memory::Usage](http://search.cpan.org/perldoc?Memory::Usage) object available to the context.

To record more measure points for the memory profiling, use the `record()`
method of that object:

    sub foo :Path {
        my ( $self, $c) = @_;

        ...

        big_stuff();

        $c->memory_usage->record( "done with big_stuff()" );

        ...
    }

## `reset_memory_usage()`

Discards the current `Memory::Usage` object, along with its recorded data,
and replaces it by a shiny new one.

# BUGS AND LIMITATIONS

`Memory::Usage`, which is the module `Catalyst::Plugin::MemoryUsage` relies
on to get its statistics, only work for Linux-based platforms. Consequently,
for the time being `Catalyst::Plugin::MemoryUsage` only work on Linux and
NetBSD. This being said, patches are most welcome. :-)

# SEE ALSO

[Memory::Usage](http://search.cpan.org/perldoc?Memory::Usage)

# AUTHOR

Yanick Champoux <yanick@babyl.dyndns.org>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Yanick Champoux.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.