/ 
Module-Lazy-0.04
River stage zero No dependents
/ Module::Lazy

NAME

Module::Lazy - postpone loading a module until it's actually used

SYNOPSIS

use Module::Lazy "My::Module";
# My::Module has not been loaded

my $var = My::Module->new;
# My::Module is loaded now, and new() method is called

no Module::Lazy;
# Force loading of all postponed modules

DESCRIPTION

In large projects loading all the dependencies may take a lot of time. This module attempts to reduce the startup time by postponing initialization. The improvement be significant for unit test scripts and small command-line tools which do not utilize all the functionality at once.

This comes at a cost of reduced stability, as load-time errors are also postponed. The no Module::Lazy directive is provided to mitigate the risk by forcing the pending modules to load.

EXPORTED FUNCTIONS

None.

METHODS

import

When use Module::Lazy "Some::Module"; is called, the module in question is not loaded. A stub package with the same name is created instead.

Should any method call be performed on the stub package, it loads the original one and jumps to respective method.

In particular, can() and isa() are overloaded and will trigger module loading.

Upon loading, import is not called on the target package. This MAY change in the future.

No extra options (except from target module name) are allowed.

unimport

Calling no Module::Lazy; or, alternatively, Module::Lazy->unimport; will cause all postponed modules to be loaded immediately, in alphabetical order.

This may be useful to avoid deferred errors and/or side effects of module loading.

No extra options to unimport are supported.

ENVIRONMENT

If PERL_LAZYLOAD_DEBUG is set and true, warns about module loading via Carp.

If PERL_LAZYLOAD_DISABLE is set and true, don't try to lazyload anything - just go straight to require.

(That's roughly equivalent to perl -M-Module::Lazy on command line).

CAVEATS

  • The following symbols are currently replaced by stubs in the module to be loaded: AUTOLOAD, DESTROY, can, isa.

  • If a module was ever lazyloaded, a normal require would do nothing. A method must be called to inflate the module.

    This is done so because a normal require would partially overwrite stub methods and potentially wreak havoc.

  • A fake $VERSION = 10**9 is generated so that use Module x.yy doesn't die. This value is erased before actually loading the module.

BUGS

  • use mro 'c3'; does not work with lazy-loaded parent classes.

  • import() is not called on the modules being loaded. The decision is yet to be made whether it's good or bad.

  • no way to preload prototyped exported functions (that's what autouse does), but maybe there should be?

  • certainly not enough interoperability tests.

Please report bugs via github or RT:

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Module::Lazy

You can also look for information at:

SEE ALSO

autouse is another module with similar idea, however, it does it for imported functions rather than methods.

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2019 Konstantin S. Uvarin, <khedin@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.