view release on metacpan or  search on metacpan

lib/slot.pm  view on Meta::CPAN

package
    slot;
use strict;
use warnings;
our $VERSION = '0.18';
require XSLoader;
XSLoader::load('slot', $VERSION);
1;

__END__

=head1 NAME

slot - global reactive state slots with optional watchers

=head1 SYNOPSIS

    # Define and use slots
    package Config;
    use slot qw(app_name debug);
    
    app_name("MyApp");
    debug(1);
    
    # Access from another package (same underlying storage)
    package Service;
    use slot qw(app_name);
    
    print app_name();  # "MyApp"
    app_name("Changed");

    # Watchers (reactive)
    slot::watch('app_name', sub {
        my ($name, $value) = @_;
        print "app_name changed to: $value\n";
    });
    
    slot::unwatch('app_name');  # Remove all watchers

=head1 DESCRIPTION

C<slot> provides fast, globally shared named storage slots.
Slots are shared across all packages - importing the same slot name in different
packages gives access to the same underlying value.

Key features:

=over 4

=item * B<Fast> - Custom ops with compile-time optimization

=item * B<Global> - Slots are shared across packages by name

=item * B<Reactive> - Optional watchers fire on value changes

=item * B<Lazy watchers> - No overhead unless you use C<watch()>

=back

=head1 COMPILE-TIME OPTIMIZATION

When you call any C<slot::*> function with a B<constant string> name for a
slot that B<exists at compile time> (created via C<use slot qw(...)>), the
call is optimized at compile time to a custom op or constant.

    use slot qw(counter);           # Creates slot at compile time
    
    slot::get('counter');           # Optimized to custom op (185% faster)
    slot::set('counter', 42);       # Optimized to custom op (283% faster)
    my $idx = slot::index('counter'); # Constant-folded (no runtime code!)
    slot::watch('counter', \&cb);   # Optimized to custom op
    slot::unwatch('counter');       # Optimized to custom op
    slot::clear('counter');         # Optimized to custom op

Variable names are NOT optimized and use the XS fallback:

    my $name = 'counter';
    slot::get($name);               # XS function call (slower)

=head2 Optimization Requirements

=over 4