NAME

Zing::Domain - Shared State Management

ABSTRACT

Shared State Management Construct

SYNOPSIS

  use Zing::Domain;

  my $domain = Zing::Domain->new(name => 'user-1');

  # $domain->recv;

DESCRIPTION

This package provides an aggregate abstraction and real-time cross-process sharable data structure which offers many benefits, not least being able to see a full history of state changes.

INHERITS

This package inherits behaviors from:

Zing::Channel

LIBRARIES

This package uses type constraints from:

Zing::Types

ATTRIBUTES

This package has the following attributes:

metadata

  metadata(HashRef)

This attribute is read-only, accepts (HashRef) values, and is optional.

METHODS

This package implements the following methods:

apply

  apply() : Object

The apply method receives events from the channel and applies the operations.

apply example #1

  # given: synopsis

  $domain->apply;

change

  change(Str $op, Str $key, Any @val) : Object

The change method commits an operation (and snapshot) to the channel. This method is used internally and shouldn't need to be called directly.

change example #1

  # given: synopsis

  $domain->change('incr', 'karma', 1);

decr

  decr(Str $key, Int $val = 1) : Object

The decr method decrements the data associated with a specific key.

decr example #1

  # given: synopsis

  $domain->decr('karma');

decr example #2

  # given: synopsis

  $domain->decr('karma', 2);

del

  del(Str $key) : Object

The del method deletes the data associated with a specific key.

del example #1

  # given: synopsis

  $domain->del('missing');

del example #2

  # given: synopsis

  $domain->set('email', 'me@example.com');

  $domain->del('email');

emit

  emit(Str $key, HashRef $data) : Object

The emit method executes any callbacks registered using the "listen" method associated with a specific key.

emit example #1

  # given: synopsis

  $domain->emit('email', { val => ['me@example.com'] });

emit example #2

  # given: synopsis

  $domain->listen('email', sub { my ($self, $data) = @_; $self->{event} = $data; });

  $domain->emit('email', { val => ['me@example.com'] });

get

  get(Str $key) : Any

The get method return the data associated with a specific key.

get example #1

  # given: synopsis

  $domain->get('email');

get example #2

  # given: synopsis

  $domain->set('email', 'me@example.com');

  $domain->get('email');

ignore

  ignore(Str $key, Maybe[CodeRef] $sub) : Any

The ignore method removes the callback specified by the "listen", or all callbacks associated with a specific key if no specific callback if provided.

ignore example #1

  # given: synopsis

  $domain->ignore('email');

ignore example #2

  # given: synopsis

  my $callback = sub { my ($self, $data) = @_; $self->{event} = $data; };

  $domain->listen('email', $callback);

  $domain->ignore('email', $callback);

ignore example #3

  # given: synopsis

  my $callback_1 = sub { my ($self, $data) = @_; $self->{event} = [$data, 2]; };

  $domain->listen('email', $callback_1);

  my $callback_2 = sub { my ($self, $data) = @_; $self->{event} = [$data, 1]; };

  $domain->listen('email', $callback_2);

  $domain->ignore('email', $callback_1);

ignore example #4

  # given: synopsis

  my $callback_1 = sub { my ($self, $data) = @_; $self->{event} = [$data, 1]; };

  $domain->listen('email', $callback_1);

  my $callback_2 = sub { my ($self, $data) = @_; $self->{event} = [$data, 2]; };

  $domain->listen('email', $callback_2);

  $domain->ignore('email');

incr

  incr(Str $key, Int $val = 1) : Object

The incr method increments the data associated with a specific key.

incr example #1

  # given: synopsis

  $domain->incr('karma');

incr example #2

  # given: synopsis

  $domain->incr('karma', 5);

listen

  listen(Str $key, CodeRef $sub) : Object

The listen method registers callbacks associated with a specific key which will be invoked by the "emit" method or whenever an event matching the key specified is received and applied.

listen example #1

  # given: synopsis

  $domain->ignore('email');

  $domain->listen('email', sub { my ($self, $data) = @_; $self->{event} = $data; });

listen example #2

  # given: synopsis

  $domain->ignore('email');

  my $callback = sub { my ($self, $data) = @_; $self->{event} = $data; };

  $domain->listen('email', $callback);

  $domain->listen('email', $callback);

listen example #3

  # given: synopsis

  $domain->ignore('email');

  my $callback_1 = sub { my ($self, $data) = @_; $self->{event} = [$data, 1]; };

  $domain->listen('email', $callback_1);

  my $callback_2 = sub { my ($self, $data) = @_; $self->{event} = [$data, 2]; };

  $domain->listen('email', $callback_2);

merge

  merge(Str $key, HashRef $val) : Object

The merge method commits the data associated with a specific key to the channel as a partial to be merged into any existing data.

merge example #1

  # given: synopsis

  $domain->merge(data => { email => 'me@example.com', username => 'me' });

  $domain->merge(data => { email => 'we@example.com' });

merge example #2

  # given: synopsis

  $domain->set(data => { username => 'we' });

  $domain->merge(data => { email => 'me@example.com', username => 'me' });

  $domain->merge(data => { email => 'we@example.com' });

merge example #3

  # given: synopsis

  $domain->set(data => { username => 'we', colors => ['white'] });

  $domain->merge(data => { email => 'me@example.com', username => 'me' });

  $domain->merge(data => { email => 'we@example.com' });

  $domain->merge(data => { colors => ['white', 'green'], username => 'we' });

pop

  pop(Str $key) : Object

The pop method pops the data off of the stack associated with a specific key.

pop example #1

  # given: synopsis

  $domain->pop('history');

push

  push(Str $key, Any @val) : Object

The push method pushes data onto the stack associated with a specific key.

push example #1

  # given: synopsis

  $domain->push('history', { updated => 1234567890 });

set

  set(Str $key, Any $val) : Object

The set method commits the data associated with a specific key to the channel.

set example #1

  # given: synopsis

  $domain->set('updated', 1234567890);

shift

  shift(Str $key) : Object

The shift method shifts data off of the stack associated with a specific key.

shift example #1

  # given: synopsis

  $domain->shift('history');

state

  state() : HashRef

The state method returns the raw aggregate data associated with the object.

state example #1

  # given: synopsis

  $domain->state;

unshift

  unshift(Str $key, Any @val) : Object

The unshift method unshifts data onto the stack associated with a specific key.

unshift example #1

  # given: synopsis

  $domain->unshift('history', { updated => 1234567890 });

AUTHOR

Al Newkirk, awncorp@cpan.org

LICENSE

Copyright (C) 2011-2019, Al Newkirk, et al.

This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file".

PROJECT

Wiki

Project

Initiatives

Milestones

Contributing

Issues

cpanm Zing

perl -MCPAN -e shell
install Zing