Stale %INC cache blocks reloading of edited Perl modules during runtime

Why the Interpreter Ignores Edited Module Files

Perl utilizes the %INC hash to track which modules have already been loaded. When a use or require statement is executed, the interpreter checks if the module's absolute path exists as a key in %INC. If the key is present, Perl assumes the module is already in memory and skips the file read entirely. Consequently, any changes made to the .pm file on disk while the process is running are ignored because the interpreter never re-examines the source file.

Confirmed Behavior and Risks

• Forcing Reloads: Deleting the specific module key from %INC (e.g., delete $INC{'My/Module.pm'};) removes the cache entry, forcing the next require to reload the file from disk.
• Symbol Persistence: Deleting the %INC entry does not remove subroutines, variables, or constants already defined in the symbol table. The new version of the module will overwrite existing subroutines, but any state stored in package variables remains unless explicitly reset.
• Resource Leaks: In long-running processes, reloading modules that perform initialization side effects (such as opening sockets or registering callbacks) can lead to resource leaks or duplicated event handlers.

Steps to Reload a Module at Runtime

1. Identify the Key: Find the exact path used in %INC. This is typically the path relative to the @INC directories.
2. Clear the Cache:

   delete $INC{'My/Module.pm'};

3. Re-execute Load:

   require 'My/Module.pm';

4. Refresh Imports: If the module exports functions, call the import method manually to update the current namespace:

   My::Module->import();

Safe Patterns for Development Reloading

When using tools like Module::Reload, follow these constraints to avoid inconsistent state:

• Environment Gating: Wrap reload logic in a conditional block so it only activates during development (e.g., if ($ENV{DEV_MODE}) { ... }).
• Idempotent Initialization: Ensure BEGIN blocks or initialization code can be run multiple times without side effects.
• Explicit State Reset: If the module maintains a singleton or global state, provide a reset() method to be called immediately after the reload.

Verifying Stale Cache Without Altering Code

To confirm a stale cache is the issue without modifying the primary application logic, you can use a debugger or an external signal handler to inspect the process state:

• Inspect %INC: Use a tool like Devel::Peek or a debug shell to check if the module path exists in %INC.
• Subroutine Address Check: Compare the memory address of a subroutine before and after a suspected reload. If the address remains identical despite a file change, the cache is blocking the update.
• Version Probing: Add a $VERSION or a dummy constant to the module. If the running process reports the old version while the disk shows the new one, the %INC entry is stale.

Diagnostic Question: Is this process running within a persistent environment such as mod_perl, Plack, or a custom daemon? This determines if the cache must be cleared per-request or only upon specific administrative triggers.