Skip to content

Latest commit

 

History

History
253 lines (127 loc) · 7.34 KB

perljava.pod

File metadata and controls

253 lines (127 loc) · 7.34 KB
Raw

NAME

perljava - PerlOnJava Portability Guide

SYNOPSIS

This document provides guidelines for writing Perl scripts that are portable when compiled and executed using PerlOnJava, a Perl compiler that translates Perl code into Java bytecode for execution on the Java Virtual Machine (JVM).

DESCRIPTION

PerlOnJava allows Perl scripts to be integrated into Java environments by compiling them into Java bytecode. This document outlines considerations and best practices for ensuring that your Perl scripts are portable and compatible with the PerlOnJava compiler.

Newlines

PerlOnJava handles newlines in a manner consistent with the JVM. Ensure that your scripts account for newline differences across platforms by using Perl's built-in functions like chomp and chop. Be aware that newline handling may vary between Unix and Windows environments.

File System

  • PerlOnJava supports basic file operations such as open, readline, and close. However, some file test operators like -R, -W, and -X are not implemented due to JVM limitations.

  • Use platform-independent file paths and avoid relying on case sensitivity, as file systems may differ between environments.

  • The stat and lstat functions are implemented, but some fields may return undef due to JVM constraints.

Command Execution

  • PerlOnJava supports executing Perl code dynamically using the eval function.

  • External command execution should be handled with care, considering the JVM's limitations and the lack of direct system call support. Use Java's process execution capabilities for more complex needs.

Character Sets and Encoding

  • PerlOnJava supports Unicode. Non-Unicode strings are not fully supported, so ensure your scripts handle character encoding appropriately.

  • Use Perl's Encode module where necessary to manage character encodings.

Networking

  • PerlOnJava does not support low-level socket functions due to JVM constraints.

  • High-level networking operations will be implemented using Java's native capabilities.

Time and Date

  • Time-related functions like time, gmtime, and localtime are implemented. However, be aware of potential differences in time zone handling across platforms.

  • The sleep function is implemented and supports fractional seconds.

Modules and Libraries

  • PerlOnJava supports a subset of Perl modules and pragmas. Refer to the FEATURE_MATRIX.md for details on supported modules.

  • Avoid using XS modules or CPAN libraries that rely on C code, as they are not compatible with the JVM.

  • The strict pragma is always enabled, and no strict is ignored. Plan your code accordingly.

Regular Expressions

  • Basic regex operations are supported, including qr//, m//, and s///. However, some Perl-specific features are missing.

  • Java's regex engine limitations may affect regex behavior, particularly with named capture groups. Features like /xx and /ee are not supported.

Scalars, Arrays, and Hashes

  • PerlOnJava supports scalar operations, including my, our, and local declarations. Tied scalars are not supported.

  • Basic array and hash operations are implemented, including push, pop, keys, and values. Tied arrays and hashes are not supported.

  • Autovivification is supported, but ensure your code does not rely on Perl-specific behaviors not implemented in PerlOnJava.

Subroutines

  • Named and anonymous subroutines are supported, including closures. Subroutine signatures and attributes are not implemented.

  • The CORE namespace is available, but CORE::GLOBAL is not implemented.

Objects

  • Object-oriented features such as bless, ref, and @ISA are supported. Multiple inheritance with C3 method resolution is implemented.

  • The AUTOLOAD mechanism is available, but ensure compatibility with JVM constraints.

Statements and Special Operators

  • Conditional statements like if, unless, and loops like for, while are supported.

  • Operators such as defined-or (//), string concatenation (.), and logical operators are implemented.

  • The goto operator is partially supported; goto LABEL and goto EXPR are not implemented.

Object Destruction and the DESTROY Method

In Perl, the DESTROY method is used to clean up an object before it is garbage collected. This method is typically used to release resources such as file handles, database connections, or other system resources that the object may hold.

Challenges with DESTROY in PerlOnJava

PerlOnJava compiles Perl code into Java bytecode, which runs on the JVM. The JVM uses a garbage collection mechanism that differs from Perl's reference counting. This difference can lead to several challenges:

  1. Timing of Object Destruction: In Perl, objects are destroyed immediately when their reference count drops to zero. In contrast, the JVM's garbage collector determines when to reclaim memory, which may not coincide with the exact moment an object becomes unreachable. This can delay the execution of the DESTROY method, potentially leading to resource leaks if resources are not released promptly.

  2. Resource Management: Since the JVM does not guarantee when or if the DESTROY method will be called, relying on it for critical resource management can be problematic. Resources such as file handles or network connections should be explicitly managed to ensure they are released promptly.

  3. Compatibility with Perl Modules: Some Perl modules rely on the DESTROY method for cleanup. When using such modules with PerlOnJava, be aware that their behavior might differ due to the JVM's garbage collection. Modules like SelectSaver and File::Temp may not function as expected because they depend on timely destruction.

Recommendations

To mitigate issues related to object destruction in PerlOnJava, consider the following best practices:

  • Explicit Resource Management: Avoid relying solely on the DESTROY method for resource cleanup. Instead, use explicit resource management techniques, such as closing file handles or database connections in a finally block.

  • Test and Validate: Thoroughly test your Perl scripts in the PerlOnJava environment to identify and address any issues related to object destruction and resource management.

Platform-Specific Notes

  • PerlOnJava is designed to run on any platform that supports the JVM. However, be mindful of platform-specific behaviors and test your scripts across different environments to ensure compatibility.

  • JVM-specific limitations may affect certain Perl features, particularly those relying on low-level system interactions.

SEE ALSO

For more details on the PerlOnJava project, refer to the README.md and FEATURE_MATRIX.md files in the project repository.

AUTHOR

Flavio S. Glock

COPYRIGHT AND LICENSE

This document is licensed under the same terms as the Perl Artistic License 2.0.