File Coverage

blib/lib/Argon.pm
Criterion Covered Total %
statement 10 10 100.0
branch 2 2 100.0
condition n/a
subroutine 4 4 100.0
pod 0 1 0.0
total 16 17 94.1


line stmt bran cond sub pod time code
1             package Argon;
2             # ABSTRACT: Simple, fast, and flexible distributed computing
3             $Argon::VERSION = '0.18';
4 3     3   24 use strict;
  3         10  
  3         118  
5 3     3   21 use warnings;
  3         9  
  3         120  
6 3     3   22 use Carp;
  3         80  
  3         363  
7              
8             our $ALLOW_EVAL = 0;
9 2 100   2 0 129 sub ASSERT_EVAL_ALLOWED { $Argon::ALLOW_EVAL || croak 'not permitted: $Argon::ALLOW_EVAL is not set' };
10              
11              
12             1;
13              
14             __END__
15              
16             =pod
17              
18             =encoding UTF-8
19              
20             =head1 NAME
21              
22             Argon - Simple, fast, and flexible distributed computing
23              
24             =head1 VERSION
25              
26             version 0.18
27              
28             =head1 DESCRIPTION
29              
30             Argon is a distributed processing platform built for Perl. It is designed to
31             offer a simple, flexible, system for quickly building scalable systems with the
32             minimum impact on existing workflows and code structure.
33              
34             =head1 QUICK START
35              
36             An argon system is controlled by a I<manager> process, whose job it is to
37             schedule tasks among registered I<workers>.
38              
39             =head2 MANAGER
40              
41             A manager process is started with C<ar-manager>. The manager, workers, and
42             clients must all use the same key (a file containing a key phrase used for
43             encryption).
44              
45             ar-manager --host localhost --port 8000 --key path/to/secret --verbose 7
46              
47             =head2 WORKER
48              
49             Workers are started with C<ar-worker> and must use the same C<key> as the
50             manager.
51              
52             ar-worker --mgr mgrhost:8000 --capacity 8 --key path/to/secret --verbose 7
53              
54             =head2 CLIENT
55              
56             Connecting to an Argon service is straightforward.
57              
58             use Argon::Client;
59             use AnyEvent;
60              
61             # Connect
62             my $cv = AnyEvent->condvar;
63              
64             my $ar = Argon::Client->new(
65             host => 'mgrhost',
66             port => 8000,
67             keyfile => 'path/to/key',
68             ready => $cv,
69             retry => 1,
70             );
71              
72             # Connected!
73             $cv->recv;
74              
75             A code ref (or any callable reference) may be passed using the C<ready>
76             parameter which will be called once the client is connected. The example uses a
77             condition variable (see L<AnyEvent/CONDITION VARIABLES>) to sleep until it
78             is called, making the connection blocking.
79              
80             =head1 RUNNING TASKS
81              
82             Once connected, there are a number of ways to schedule tasks with the manager,
83             the most basic being the L<Argon::Client/queue> method.
84              
85             $client->queue('My::Task::Class', $arg_list, sub {
86             my $reply = shift;
87             my $result = $reply->result;
88             });
89              
90             There are a couple things to note here. The task class is any class that
91             defines both a C<new> and a C<run> method. The C<$arg_list> will be passed to
92             C<new>. A subroutine is passed which is called when the result is ready. The
93             call to the C<result> method will C<croak> if the task failed.
94              
95             If C<retry> was set when the client was connected, the task will retry on a
96             logarithmic backoff until the server has the capacity to process the task
97             (see L<Argon/PREDICTABLE PERFORMANCE DEGREDATION>).
98              
99             If the workers were started with the C<--allow-eval> switch, the client may
100             pass code references directly to be evaluated by the workers using the
101             L<Argon::Client/process> method.
102              
103             local $Argon::ALLOW_EVAL = 1;
104              
105             $client->process(sub { ... }, $arg_list, sub {
106             ...
107             });
108              
109             =head1 PREDICTABLE PERFORMANCE DEGREDATION
110              
111             One of the key problems with many task queue implementations is the manner in
112             which the system recovers from an interruption in service. In most cases, tasks
113             continue to pile up while the system is unavailable. Once the service is again
114             ready to process tasks, a significant backlog has built up, creating further
115             delay for new tasks added to the queue. This creates a log jam that is often
116             accompanied by incidental service slowdowns that can be difficult to diagnose
117             (for example, overloaded workers clearing out the backlog tie up the database,
118             causing other services to slow down).
119              
120             Argon prevents these cases by placing the responsibility for the backlog on the
121             client. When the manager determines that the system has reached max capacity,
122             new tasks are I<rejected> until there is room in the queue. From the
123             perspective of the client, there is still a delay in the processing of tasks,
124             but the task queue itself never becomes overloaded and the performance
125             degredation will never overflow onto neighborhing systems as a result.
126              
127             Another adavantage of having a bounded queue is that clients are aware of the
128             backlog and may report this to callers. System administrators may effectively
129             plan for and respond to increased load by spinning up new servers as needed
130             because they can reliably predict the performance of the system under load
131             given a reliable estimate of the cost imposed by the tasks being performed.
132              
133             =head1 AUTHOR
134              
135             Jeff Ober <sysread@fastmail.fm>
136              
137             =head1 COPYRIGHT AND LICENSE
138              
139             This software is copyright (c) 2017 by Jeff Ober.
140              
141             This is free software; you can redistribute it and/or modify it under
142             the same terms as the Perl 5 programming language system itself.
143              
144             =cut