/ 
Module-Generic-v1.0.4
River stage two • 17 direct dependents • 20 total dependents
/ Module::Generic::DateTime

NAME

Module::Generic::DateTime - A DateTime wrapper for enhanced features

SYNOPSIS

use Module::Generic::DateTime;

my $dt = DateTime->new;
my $gdt = Module::Generic::DateTime->new( $dt );
# or directly will instantiate a default DateTime value based on DateTime->now
my $gdt = Module::Generic::DateTime->new;

# Now you can do operations that are not normally possible with DateTime
# Compare a dt object with a unix timestamp
if( $gdt > time() )
{
    # do something
}
elsif( $gdt < '2020-03-01 07:12:10+0900' )
{
    # do something
}
# and of course, comparison with other dt works as before
elsif( $gdt >= $dt )
{
    # do something
}

# Remove 10 seconds from time object
$gdt -= 10;
# Add 5 seconds and get a new object
my $dt2 = $gdt + 5;

# Get the difference as an interval between two objects
my $interval = $dt1 - $dt2;
# DateTime::Duration are represented by Module::Generic::DateTime::Interval
# and extra manipulations are possible
# Add 7 seconds
$int += 7;
# Change the days
$int->days( 5 );
# or using lvalue
$int->days = 5;
# or multiply everything (years, months, weeks, days, hours, minutes, seconds and nanoseconds) in the interval by 2
$int *= 2
# Multiply one interval by another:
my $new_interval = $int1 * $int2;
# or multiply with assignment
$int1 *= $int2;
# Then add the interval to the datetime object
$dt += $int;

VERSION

v0.6.2

DESCRIPTION

Module::Generic::DateTime is a thin wrapper around DateTime to provide additional features as exemplified above.

It also enables the DateTime object to be thawed and frozen and converted to JSON with the respective methods STORABLE_freeze, STORABLE_thaw, TO_JSON

All other method calls not in this API are passed to DateTime using AUTOLOAD with the added benefit that, if a method called triggers a fatal exception, it is caught using Nice::Try try-catch block and an error is set and return is returned instead.

CONSTRUCTOR

new

Provided with an optional DateTime object and this returns a new instance of Module::Generic::DateTime.

If no DateTime object was provided, this will instantiate one implicitly and set the formatter to stringify it to an iso8601 string, such as: 2022-03-08T14:22:10+0000. By default the instantiated DateTime object use the default time zone, which is GMT. You can change the time zone afterward using "set_time_zone" in DateTime:

$dt->set_time_zone( 'Asia/Tokyo' );

from_epoch

my $d = Module::Generic::DateTime->from_epoch( epoch => $unix_timestamp );

Instantiate a new Module::Generic::DateTime using the DateTime method from_epoch. Any parameters are passed through to "from_epoch" in DateTime

If a DateTime error occurs, it will be caught and an error will be set and undef will be returned.

now

my $d = Module::Generic::DateTime->now;

Instantiate a new Module::Generic::DateTime using the DateTime method now. Any parameters are passed through to "now" in DateTime

If a DateTime error occurs, it will be caught and an error will be set and undef will be returned.

METHODS

as_string

This is an alias to "stringify"

datetime

Sets or gets the underlying DateTime object.

op

This method is called to overload the following operations:

  • "" stringification

  • bool

  • > greater than

  • => greater or equal than

  • < lower than

  • <= lower or equal than

  • == euqal

  • != not equal

  • - minus

  • + plus

op_minus_plus

This methods handles cases of overloading for minus and plus

SERIALISATION

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw

Additionally, upon loading Module::Generic::DateTime, it will ensure the following DateTime modules also have a FREEZE and THAW subroutines if not defined already: DateTime, DateTime::TimeZone, DateTime::TimeZone::OffsetOnly, DateTime::Locale::FromData, DateTime::Locale::Base

THREAD & PROCESS SAFETY

Module::Generic::DateTime is designed to be fully thread-safe and process-safe, ensuring data integrity across Perl ithreads and mod_perl’s threaded Multi-Processing Modules (MPMs) such as Worker or Event. It relies on Module::Generic::Global for thread-safe storage of shared state and employs synchronisation mechanisms to prevent data corruption and race conditions.

Synchronisation Mechanisms

  • Shared State

    The module uses Module::Generic::Global to cache the availability of the system’s local timezone in the local_tz namespace, storing a boolean (0 or 1) indicating whether the local timezone is supported. This repository is :shared when CAN_THREADS is true (Perl supports ithreads), protected by "lock" in perlfunc for Perl threads or APR::ThreadRWLock for mod_perl threaded MPMs without threads. In non-threaded environments, the repository is shared across processes, requiring no additional synchronisation.

  • DateTime Operations

    Methods like "op" and "op_minus_plus" perform timezone checks and DateTime operations, which are thread-safe as they rely on Module::Generic::Global’s synchronisation. The underlying DateTime module is thread-safe for most operations, and this module ensures no shared mutable state is accessed without proper locking.

Context Key Isolation

The local_tz namespace uses a class-level key (<class>), where class is Module::Generic::DateTime. This ensures timezone support is cached across processes, with no thread-specific granularity needed, as timezone availability is a global property. The key format enables cross-process sharing, and threaded environments (HAS_THREADS true) maintain isolation via Module::Generic::Global’s synchronisation.

mod_perl Considerations

  • Prefork MPM

    Data is cross-process, requiring no additional synchronisation, as all processes share the same local_tz repository.

  • Threaded MPMs (Worker/Event)

    The local_tz repository is shared across threads and processes, protected by Module::Generic::Global’s synchronisation. Users should call Module::Generic::Global-cleanup_register> in mod_perl handlers to clear the repository after requests, preventing memory leaks in long-running processes.

  • Thread-Unsafe Functions

    Avoid Perl functions like localtime, readdir, srand, or operations like chdir, umask, chroot in threaded MPMs, as they may affect all threads. Consult perlthrtut and mod_perl documentation for details.

Thread-Safety Considerations

The module’s thread-safety relies on:

  • Shared Repository: The local_tz namespace is initialised as :shared when CAN_THREADS is true, ensuring safe access across threads and processes.

  • Locking: "lock" in perlfunc or APR::ThreadRWLock protects all read/write operations to the repository.

  • Immutable State: Beyond local_tz, the module avoids shared mutable state, relying on DateTime’s thread-safe operations.

In environments where %INC manipulation (e.g., by forks) emulates threads, HAS_THREADS and IN_THREAD may return true. This is generally safe, as forks provides a compatible tid method, but users in untrusted environments should verify $INC{'threads.pm'} points to the actual threads module.

For maximum safety, users running mod_perl with threaded MPMs should ensure Perl is compiled with ithreads and explicitly load threads, or use Prefork MPM for single-threaded operation.

SEE ALSO

Module::Generic, Module::Generic::DateTime::Interval, DateTime, DateTime::Format::Strptime, DatetTime::TimeZone

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright (c) 2000-2024 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.