view release on metacpan or  search on metacpan

lib/App/Chart/Glib/Ex/DirBroadcast.pm  view on Meta::CPAN

  }
}

sub hold {
  my ($self) = @_;
  ref($self) or $self = $self->instance;
  return App::Chart::Glib::Ex::DirBroadcast::Hold->new ($self);
}

package App::Chart::Glib::Ex::DirBroadcast::Hold;
use strict;
use warnings;

sub new {
  my ($class, $dirb) = @_;
  my $self = bless { }, $class;
  $self->{'target'} = $dirb;
  require Scalar::Util;
  Scalar::Util::weaken ($self->{'target'});
  $dirb->{'hold'} ++;
  return $self;
}

sub DESTROY {
  my ($self) = @_;
  my $dirb = delete $self->{'target'} || return;
  if (-- $dirb->{'hold'}) { return; }

  my $hold_list = $dirb->{'hold_list'};
  ### DirBroadcast::Hold now run: $hold_list
  while (my $subr = shift @$hold_list) {
    $subr->();
  }
}

1;
__END__

=head1 NAME

App::Chart::Glib::Ex::DirBroadcast -- broadcast messages through a directory of named pipes

=head1 SYNOPSIS

 use App::Chart::Glib::Ex::DirBroadcast;
 App::Chart::Glib::Ex::DirBroadcast->directory ('/my/directory');
 App::Chart::Glib::Ex::DirBroadcast->listen;

 App::Chart::Glib::Ex::DirBroadcast->connect ('my-key', sub { print @_; });

 App::Chart::Glib::Ex::DirBroadcast->send ('my-key', "hello\n");

=head1 DESCRIPTION

DirBroadcast is a message broadcasting system based on named pipes in a
given directory, with a Glib main loop IO watch listening and calling
connected handlers.  It's intended for use between multiple running copies
of a single application so they can notify each other of changes to files
etc.

Messages have a string "key" which is a name or type decided by the
application, and then any parameters which Storable can handle
(L<Storable>).  You can have either a single broadcast directory used for
all purposes, or create multiple DirBroadcast objects.  The method functions
described below take either the class name C<App::Chart::Glib::Ex::DirBroadcast> for the
single global, or a DirBroadcast object.

=head1 FUNCTIONS

=over 4

=item C<< App::Chart::Glib::Ex::DirBroadcast->new ($directory) >>

Create and return a new DirBroadcast object communicating through the given
C<$directory>.  C<$directory> is created if it doesn't already exist (with a
C<croak> if that fails).

    my $dirb = App::Chart::Glib::Ex::DirBroadcast->new ('/var/run/myapp')

=item C<< App::Chart::Glib::Ex::DirBroadcast->directory ($directory) >>

=item C<< App::Chart::Glib::Ex::DirBroadcast->directory () >>

=item C<< $dirb->directory ($directory) >>

=item C<< $dirb->directory () >>

Get or set the filesystem directory used for broadcasts.

=item C<< App::Chart::Glib::Ex::DirBroadcast->send ($key, $data, ...) >>

=item C<< App::Chart::Glib::Ex::DirBroadcast->send_locally ($key, $data, ...) >>

=item C<< $dirb->send ($key, $data, ...) >>

=item C<< $dirb->send_locally ($key, $data, ...) >>

Send a message of C<$key> and optional C<$data> values.  C<send> broadcasts
to all processes, including the current process, or C<send_locally> just to
the current process.

A send within the current process just means direct calls to functions
registered by C<connect> below.  This takes place immediately within the
C<send> or C<send_locally>, there's no queuing and the current process
doesn't have to have a C<listen> active.

The data values can be anything C<Storable> can freeze (see L<Storable>).
For C<send_locally> there's no copying, the values are simply passed to the
connected functions, so the values can be anything at all.

=item C<< App::Chart::Glib::Ex::DirBroadcast->listen () >>

=item C<< $dirb->listen () >>

Create a named pipe in the broadcast directory to receive messages from
other processes, and setup a C<< Glib::IO->add_watch >> to call the
functions registered with C<connect> when a message is received.

=item C<< App::Chart::Glib::Ex::DirBroadcast->connect ($key, $subr) >>

=item C<< $dirb->connect ($key, $subr) >>