Moving from CGI to mod_perl. Understanding my, our, local

mod-perl, mod-perl2, perl, scope

Solution

mod_perl works by wrapping each Perl script in a subroutine called `handler` within a package based on the name and path of the script. Instead of starting a new process to run each script, this `handler` subroutine is called by one of a number of persistent Perl theads.

Ordinarily this knowledge would help a lot to understand the changes in environment from mod_cgi, but since you have never added `use strict` to your programs and become familiar with the workings of declared variables you have a lot of catching up to do!

The mod_perl environment has the potential for causing non-obvious security breaches, and you should start now to `use strict` on every script and declare every variable. `use Carp` will also help you to understand the error logs.

A variable name declared with `our` is a lexically-scoped synonym for a package variable of the same name that can be used without fully qualifying the name by including the package name. For instance, ordinarily a variable declared with `our $var` will provide access to the `$main::var` scalar (if there has been no preceding `package` declaration) without specifying `main::`. However, such variables that began life with a value of `undef` in mod_cgi will now retain their values from the previous execution of any given mod_perl thread, and for consistency it is safest to always initialise them at the point of declaration. Note also that the default package name is no longer `main` because of the wrapping that mod_perl does, so you can no longer access package variables using the `main::` prefix, and it is unwise to find the actual name of the package and explicitly use that because it will be a very long name and will change if you move or rename your script.

A `my` variable is one that exists independently of the package symbol table, and normally its lifetime is the run time of the enclosing file (for variables declared at file scope) or subroutine. They are safe in mod_perl if both declared and used at file scope of the script or entirely within one subroutine, but you can be stung if you mix scopes and declare a `my $global` at file scope and then try to use it in a subroutine. The reason for this isn't simple, but it is caused by mod_perl wrapping your script in a `handler` subroutine so you have nested subroutine declarations. The inner subroutine will tend to adopt only the first instantiation of `$global` and ignore any others created by later calls to `handler`. If you need a global variable you should declare it with `our` and initialise it in that declaration as described above.

A `local` variable is very like an `our` variable in that it forms a synonym to a package variable. However it temporarily saves the current value of that variable and provides a new copy for use until the end of the file or block scope. Because of its automatic creation and deletion within its scope it can be a useful alternative to a `my` variable in mod_perl scripts, particularly where you are using pointers to data structures like, say, an instance of the `CGI` class. Declaring `our $cgi = CGI->new` would correctly create the object but, because of mod_perl's persistence, would leave it in memory until the next execution of the thread deletes it to make room for another one.

As for your questions:

Using a variable without declaring it either causes a compile-time error if `use strict` is in place as it should be. Otherwise it is a synonym for that variable in the current package namespace.

Variables are either package variables or lexical variables; there is no way to declare a variable as private as such. Lexical variables (declared with `my`) will be created and destroyed with each execution of the script, unless you have created an invalid closure as described above by writing a subroutine that uses a variable declared at a wider scope, when the variable will be persistent but won't do what you want it to. A variable declared with `our` will retain its value across calls to the script, while one declared with `local` will be destroyed when the script terminates. Both `our` and `local` variables are package variables and all references to the same variable name refer to the same variable.

To declare a variable that is consistently accessible everywhere within any one call of a script you can either use a `local` variable or an initialised `our` variable. At file scope `local $global` is largely equivalent to `our $global = undef` for mod_perl scripts. If you use an `our` variable to point to a data structure then remember to destroy it at the end of the script with `undef $global`.

`my` variables are unique to, and visible within, the block in which they are declared, whether that is a block within an `if`, `while` or `for`, or even just a bare `{ ... }` block scope. Always use `my` variables for temporary work variables that are used only within a block and accessed from nowhere else.

I hope this helps

Problem

Original source