load(3pm)

📦

version 0.26 · 2 versions

0.26 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
0.24 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu resolute, ubuntu stonking

✨ load — control when subroutines will be loaded ✨

okay so bestie, this is load(3pm), and it's genuinely one of the cutest little pragmas in Perl's whole wardrobe. Let's get into it 💖

🌸 NAME 🌸

load — control when subroutines will be loaded

💅 SYNOPSIS 💅

use load;            # default, same as 'autoload'

use load 'autoload'; # export AUTOLOAD handler to this namespace

use load 'ondemand'; # load subroutines after __END__ when requested, default

use load 'now';      # load subroutines after __END__ now

use load ();         # same as qw(dontscan inherit)

use load 'dontscan'; # don't scan module until it is really needed

use load 'inherit';  # do NOT export AUTOLOAD handler to this namespace

🦋 VERSION 🦋

This documentation describes version 0.26.

👑 DESCRIPTION 👑

So the load pragma is basically a little gift from the module developer to the application developer, giving them more options when it comes to optimizing for memory vs CPU usage. The load pragma hands over more control over the moment when subroutines get loaded and start hogging memory. Which means:

the app developer can optimize for CPU usage by loading a whole module at compile time — that way less CPU gets burned while the app is actually running;
or the app developer can optimize for memory usage by loading subroutines only when they're genuinely needed — but that, in turn, means more CPU gets used while the app runs.

The load pragma is lowkey doing the most: it combines the best of both worlds from AutoLoader and SelfLoader. And then it adds some extra features on top, because why not 💁

In a situation where you want to use as little memory as possible, the load pragma — in the context of a module — is a drop-in replacement for AutoLoader. But for situations where you want a module to load everything it could ever possibly need (e.g. when starting a mod_perl server in pre-fork mode), the load pragma can be used — this time in the context of an application — to have all subroutines of a module loaded without having to make any change to the source of the module in question. no cap.

So the typical use inside a module is to have this in the source:

package Your::Module;
use load;

...and to place all the subroutines you want loadable on demand after the (first) __END__.

If an application developer decides that all subroutines should be loaded at compile time, (s)he can say this in the application:

use load 'now';
use Your::Module;

This will cause the subroutines of Your::Module to all be loaded at compile time. slay.

🌈 MODES OF OPERATION 🌈

There are basically two places where you can call the load pragma:

🎀 inside a module 🎀

When you call the load pragma inside a module, you're basically enabling that module for having an external control over when certain subroutines will be loaded. As with AutoLoader, any subroutines that should be loaded on demand should be located after an __END__ line.

If no parameters are specified with the use load, then the autoload parameter is assumed. Whether the module's subroutines are loaded at compile time or on demand is determined by the calling application. And if the application doesn't specify anything specific, the ondemand keyword will also be assumed.

🎀 inside an application 🎀

When you call the load pragma inside an application, you're basically specifying when subroutines will be loaded by load-enhanced modules. As an application developer, you can basically use two keywords: ondemand and now.

If an application does not call the load pragma, the ondemand keyword will be assumed. With ondemand, subroutines will only be loaded when they are actually executed. This saves memory at the expense of extra CPU the first time the subroutine is called.

The now keyword indicates that all subroutines of all modules that are enhanced with the load pragma will be loaded at compile time — thus using more memory, but not having an extra CPU overhead the first time the subroutine is executed.

⭐ KEYWORDS ⭐

The following keywords are recognized with the use command:

🫶 ondemand 🫶

The ondemand keyword indicates that subroutines, of modules that are enhanced with the load pragma, will only be loaded when they are actually called.

If the ondemand keyword is used in the context of an application, all modules that are subsequently used will be forced to load subroutines only when they are actually called (unless the module itself forces a specific setting).

If the ondemand keyword is used in the context of a module, it indicates that the subroutines of that module should always be loaded when they are actually needed. Since this takes away the choice from the application developer, the use of the ondemand keyword in module context is not encouraged. See also the now and dontscan keywords.

🫶 now 🫶

The now keyword indicates that subroutines, of modules that are enhanced with the load pragma, will be loaded at compile time.

If the now keyword is used in the context of an application, all modules that are subsequently used will be forced to load all subroutines at compile time (unless the module forces a specific setting itself).

If the now keyword is used in the context of a module, it indicates that the subroutines of that module should always be loaded at compile time. Since this takes away the choice from the application developer, the use of the now keyword in module context is not encouraged. See also the ondemand keyword.

🫶 dontscan 🫶

The dontscan keyword only makes sense when used in the context of a module. Normally, when a module that is enhanced with the load pragma is compiled, the source after the __END__ is scanned for the locations of the subroutines. This makes the compiling of modules a little slower, but allows for a faster (initial) lookup of (yet) unloaded subroutines during execution.

If the dontscan keyword is specified, this scanning of the source is skipped at compile time. However, as soon as an attempt is made to execute a subroutine from this module, then first the scanning of the source is performed, before the subroutine in question is loaded.

So, you should use the dontscan keyword if you are reasonably sure that you will only need subroutines from the module in special cases. In all other cases it will make more sense to have the source scanned at compile time.

The dontscan keyword will be ignored if an application developer forces subroutines to be loaded at compile time with the now keyword.

🫶 autoload 🫶

The autoload keyword only makes sense when used in the context of a module. It indicates that a generic AUTOLOAD subroutine will be exported to the module's namespace. It is selected by default if you use the load pragma without parameters in the source of a module. See also the inherit keyword to not export the generic AUTOLOAD subroutine.

🫶 inherit 🫶

The inherit keyword only makes sense when used in the context of a module. It indicates that no AUTOLOAD subroutine will be exported to the module's namespace. This can e.g. be used when you need to have your own AUTOLOAD routine. That AUTOLOAD routine should then contain:

$load::AUTOLOAD = $sub;
goto &load::AUTOLOAD;

...to access the load pragma functionality. Another case to use the inherit keyword would be in a sub-class of a module which also is load enhanced. In that case, the inheritance will cause the AUTOLOAD subroutine of the base class to be used, thereby accessing the load pragma automagically (and hence the naming of the keyword of course). See also the autoload keyword to have the module use the generic AUTOLOAD subroutine.

🫶 AutoLoader 🫶

The AutoLoader keyword enables AutoLoader emulation mode. It basically takes over the functionality of the AutoLoader module (which is part of Perl's core, and which is used by many of Perl's core modules).

Use of AutoLoader emulation mode usually only makes sense in a mod_perl prefork environment (in combination with the now keyword), or a threaded Perl environment.

It basically adds the flexibility of subroutine loading options of the load pragma to the existing codebase of Perl's core and CPAN modules. It is typically invoked from the command line:

perl -Mload=AutoLoader

...or in a mod_perl configuration:

<Perl>
use load qw(AutoLoader now); # as early as possible
                             # rest of modules to be loaded
</Perl>

The AutoLoader emulation mode has the further advantage for modules being developed with AutoLoader, as it is possible to run the module before having to have installed the module (which is normally a requirement with using AutoLoader).

💀 okay important heads-up bestie: AutoLoader emulation will only work properly for any modules loaded after the load module is loaded. It is therefore important to activate the AutoLoader as soon as possible, before any other modules have been loaded. Of particular interest in this respect are the threads and the ifdef modules.

🍓 REQUIRED MODULES 🍓

 (none)

...and that's only part 1, so don't go anywhere 💜

🦋 DIFFERENCES WITH SIMILAR MODULES 🦋

okay so there are a bunch of (core) modules that more or less do the same thing as the load pragma, and bestie we need to talk about them because people WILL ask.

🌸 AutoSplit / AutoLoader 🌸

The load pragma is very similar to the AutoSplit / AutoLoader combo. The main difference? The splitting happens when the load import gets called in a module, and there are no external files created. Instead, just the offsets and lengths are recorded in a hash (when ondemand is active) or all the source after __END__ is eval'led (when now is active).

From a module developer point of view, the advantage is that you do not need to install a module before you can test it. From an application developer point of view, you have the flexibility of having everything loaded now or later (on demand). iconic tbh.

From a memory usage point of view, the load offset/length hash takes up more memory than the equivalent AutoLoader setup. On the other hand, accessing the source of a subroutine may generally be faster because the file is more likely to reside in the operating system's buffers already. ✨

As an extra feature, the load pragma lets an application force all subroutines to be loaded at compile time, which is not possible with AutoLoader. 👑

The "AutoLoader emulation" mode causes AutoLoader to be replaced by load, increasing further flexibility in loading options (which can be particularly important in the mod_perl prefork situation) and ease of use during development of modules using AutoLoader (as you don't need to install the module before you can test it).

🎀 SelfLoader 🎀

The load pragma also has some functionality in common with the SelfLoader module. But it gives more granularity: with SelfLoader, all subroutines that are not loaded directly will be loaded if any not yet loaded subroutine is requested. It also adds complexities if your module needs to use the <DATA> handle. So the load pragma gives more flexibility and fewer development complexities. And of course, an application can force all subroutines to be loaded at compile time when needed with the load pragma. 💅

💜 UNIVERSAL::can 💜

To ensure the functioning of the ->can class method and &UNIVERSAL::can, the load pragma hijacks the standard UNIVERSAL::can routine so that it can check whether the subroutine/method that you want to check for, actually exists and have a code reference to it returned. This has a side effect that the subroutine you checked for, is loaded. You can use this side effect to load subroutines without calling them.

Your::Module->can( 'loadthisnow' );

will load the subroutine loadthisnow of the Your::Module module without actually calling it. sneaky but make it fashion 💅

😭 CAVEATS 😭

Currently you may not have multiple packages in the same file, nor can you have fully qualified subroutine names.

The parser that looks for package names and subroutines is not very smart. This is intentionally so, as making it smarter will make it a lot slower, but probably still not smart enough. Therefore, the package and sub's must be at the start of a line. And the name of the sub must be on the same line as the sub. no cap, that's just how it is.

✨ EXAMPLES ✨

Some code examples. Please note that these are just a part of an actual situation. 🫶

🌈 base class 🌈

package Your::Module;
use load;

Exports the generic AUTOLOAD subroutine and adheres to whatever the application developer specifies as mode of operation.

🦋 sub class 🦋

package Your::Module::Adapted;
@ISA = qw(Your::Module);
use load ();

Does not export the generic AUTOLOAD subroutine, but inherits it from its base class. Also implicitely specifies the dontscan keyword, causing the source of the module to be scanned only when the first not yet loaded subroutine is about to be executed. If you only want to have the inherit keyword functionality, then you must specify that explicitly:

package Your::Module::Adapted;
@ISA = qw(Your::Module);
use load 'inherit';

💖 custom AUTOLOAD 💖

package Your::Module;
use load 'inherit';

sub AUTOLOAD {
  if (some condition) {
    $load::AUTOLOAD = $Your::Module::AUTOLOAD;
    goto &load::AUTOLOAD;
  }
  # do your own stuff
}

If you want to use your own AUTOLOAD subroutine, but still want to use the functionality offered by the load pragma, you can use the above construct. main character energy fr fr.

🔥 mod_perl prefork 🔥

use load qw(AutoLoader now);
use Your::Module;

In pre-fork mod_perl applications (the default mod_perl applications before mod_perl 2.0), it is advantageous to load all possible subroutines when the Apache process is started. This is because the operating system will share memory using a process called "Copy On Write". So even though it will take more memory initially, that memory loss is easily evened out by the gains of having everything shared. Loading a not yet loaded subroutine in that situation, will cause otherwise shared memory to become unshared. Thereby increasing the overall memory usage, because the amount that becomes unshared is typically a lot more than the extra memory used by the subroutine (which is caused by fragmentation of allocated memory).

The AutoLoader emulation mode causes all modules that use AutoLoader to be handled by load. In combination with the now mode, this means that many system modules will also be loaded completely at server startup (causing a grow in initial use of memory, but sharing more memory means that overall memory usage is significantly reduced.

🧚 threaded applications and mod_perl worker 🧚

use Your::Module;

Threaded Perl applications, of which mod_perl applications using the worker module are a special case, function best when subroutines are only loaded when they are actually needed. This is caused by the nature of the threading model of Perl, in which all data-structures are copied to each thread (essentially forcing them to become unshared as far as the operating system is concerned).

Benchmarks have shown that the overhead of the extra CPU is easily offset by the reduction of the amount of data that needs to be copied (and processed) when a thread is created. 📉

A little additional memory reduction can be achieved with the AutoLoader emulation mode: this will prevent the AutoLoader module to be loaded (but have its functionality handled by the load pragma).

🌸 SOURCE FILTERS 🌸

If your module wants to use load to load subroutines on demand and that module needs a source filter (which is usually activated with a use statement), then those modules need to be used when the source of the subroutine is compiled. The class method register is intended to be used from such a module, typicallly like this:

sub import {
  my $package = caller();
  load->register( $package,__PACKAGE__ )  # register caller's package
   if defined( $load::VERSION )           # if load.pm loaded
    and $load::VERSION > 0.11;            # and recent enough
}

The first parameter is the name of the package in which subroutines need extra modules used. The second parameter is the name of the module that needs to be used. 🫶

⭐ TODO ⭐

The coordinates of a subroutine in a module (start,number of bytes) are stored in a hash in the load namespace. Ideally, this information should be stored in the stash of the module to which they apply. Then the internals that check for the existence of a subroutine, would see that the subroutine doesn't exist (yet), but that there is an offset and length (and implicitely, a file from %INC) from which the source could be read and evalled.

Loading all of the subroutines should maybe be handled inside the Perl parser, having it skip __END__ when the global now flag is set.

Possibly we should use the <DATA> handle from a module if there is one, or dup it and use that, rather than opening the file again.

Add SelfLoader emulation mode.

👑 MODULE RATING 👑

If you want to find out how this module is appreciated by other people, please check out this module's rating at <http://cpanratings.perl.org/l/load> (if there are any ratings for this module). If you like this module, or otherwise would like to have your opinion known, you can add your rating of this module at <http://cpanratings.perl.org/rate/?distribution=load>. 💖

🎀 ACKNOWLEDGEMENTS 🎀

Frank Tolstrup for helping ironing out all of the Windows related issues. 🫡

💜 AUTHOR 💜

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Maintained by lnation <email@lnation.org>

Please report bugs to <email@lnation.org>.

🌈 COPYRIGHT 🌈

Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2010, 2012 Elizabeth Mattijsen <liz@dijkmat.nl>. 2019->2025 LNATION <email@lnation.org> All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🦋 SEE ALSO 🦋

AutoLoader, SelfLoader, ifdef, threads.

okay bestie that's the whole page 💅 this one came from perl v5.40.1 and it was dated 2025-04-24 — so yeah, freshly stamped, go forth and use load; responsibly 🫶✨

📦 where this page comes from

debian trixie: libload-perl 0.26-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libload-perl 0.26-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libload-perl 0.26-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms