blib/lib/Acme/Urinal.pm

filter: Statementstmt 90.0% 63 / 70 Branchbran 89.4% 34 / 38 Conditioncond 75.0% 36 / 48 MC/DCmcdc 50.0% 12 / 24 Subroutinesub 100% 8 / 8 Podpod 100% 5 / 5 totaltotal 81.8% 158 / 193 CC 37 SCAR 26.6
CC
37
Cov
85%
pick_one
20.2
look
15.3
pick
3.2
CRAP 14.3
↑ Summary
1 package Acme::Urinal;
2 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 1 our $VERSION = '1.0';
8  
9 =head1 NAME
10  
11 Acme::Urinal - assign resources using the same algorithm used by men choosing which urinal to use
12  
13 =head1 SYNOPSIS
14  
15 use Acme::Urinal;
16  
17 my $urinals = Acme::Urinal->new(8);
18  
19 say $urinal->pick_one; # prints 1
20 say $urinal->pick_one; # prints 3
21 say $urinal->pick_one; # prints 5
22 say $urinal->pick_one; # prints 7
23 say $urinal->pick_one; # prints 2
24 say $urinal->pick_one; # prints 4
25 say $urinal->pick_one; # prints 6
26 say $urinal->pick_one; # prints 0
27 say $urinal->pick_one; # prints nothing, triggers an uninit warning
28  
29 $urinal->leave(3);
30 $urinal->leave(4);
31 say $urinal->pick_one; # prints 4
32  
33 $urinal->leave(2);
34 $urinal->leave(1);
35 say $urinal->pick_one; # prints 1
36  
37  
38 =head1 DESCRIPTION
39  
40 When men use a bathroom with multiple urinals. The way the urinal to use is
41 chosen is nearly deterministic. This module allocates resources in a way that
42 emulates this process.
43  
44 Basically, a L<Acme::Urinal> object keeps track of a list of resources. You can
45 then request these resources be allocated and used by asking for one using the
46 L</pick_one> method. It will return the next resource according to the
47 algorithm. Once finished suing that resource, you may return it using the
48 L</leave> method.
49  
50 Each resource is chosen according to the following rules:
51  
52 =over
53  
54 =item 1.
55  
56 If possible, the lowest index resource that has a free resource on either side
57 is chosen.
58  
59 =item 2.
60  
61 Failing that, the lowest index resource with a lesser neighbor free is chosen.
62  
63 =item 3.
64  
65 Failing that, the lowest index resource with a greater neighbor free is chosen.
66  
67 =item 4.
68  
69 Failing that, the lowest index resource that is not at either end is chosen
70 (because those end ones usually tend to be the less preferable low urinal).
71  
72 =item 5.
73  
74 Finally, the lowest index resource that is available is chosen.
75  
76 =back
77  
78 =head1 METHODS
79  
80 =head2 new
81  
82 my $urinal = Acme::Urinal->new($count);
83 my $urinal = Acme::Urinal->new(\@resources);
84  
85 Constructs a new Acme::Urinal object. If the argument is a positive integer, it
86 is the same as if an array reference were passed like this:
87  
88 [ 0 .. $count ]
89  
90 If an array reference is passed, the object will use that array as the list of
91 resources. The array will be copied, so changes to the original, won't change
92 the one used by Acme::Urinal.
93  
94 Anything else should cause an error.
95  
96 =cut
97  
98 2 ▶sub new {
Subroutine new: called CC=3 SCAR=11.6
Pod documented
99 2 my ($class, $resources) = @_;
100  
101 2 ▶ if (ref $resources) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $resources) { } 0 2 2
elsif ($resources > 0) { } 1 1 2
102 0 return bless [ map { [ 0, $_ ] } @$resources ], $class;
103 }
104 elsif ($resources > 0) {
105 1 return bless [ map { [ 0, $_ ] } 0 .. ($resources - 1) ], $class;
106 }
107 else {
108 1 croak "incorrect argument";
109 }
110 }
111  
112 =head2 pick_one
113  
114 my $index = Acme::Urinal->pick_one;
115 my ($index, $resource, $comfort_level) = Acme::Urinal->pick_one;
116  
117 This will choose an available resource from those available using the algorithm
118 described in the L</DESCRIPTION>. If no resource is available, the return will
119 be C<undef> or an empty list.
120  
121 In scalar context, the index of the resource is returned. In list context, a
122 three-element list is returned where the first element is the index, the second
123 is the resource that was allocated, and the third is the comfort level with
124 which the resource was allocated. The higher the level, the better the
125 allocation was (the earlier the rule from the L</DESCRIPTION> that was used to
126 make the allocation). Currently, the comfort level will be between 1 and 5.
127  
128 =cut
129  
130 11 ▶sub pick_one {
Subroutine pick_one: called CC=20 SCAR=30.1
Pod documented
131 11 my ($self) = @_;
132  
133 11 my $choice_score = 0;
134 11 my $best_choice;
135 11 for my $i (0 .. $#$self) {
136 71 my ($in_use, $resource) = @{ $self->[$i] };
137  
138 71 ▶ next if $in_use;
Branch: 1 branch
BranchTrueFalseTotal
if $in_use 43 28 71
139  
140 28 ▶ if ($choice_score < 5 and $i > 0 and $i < $#$self and not($self->[$i - 1][0]) and not($self->[$i + 1][0])) {
Branch: 5 branches
BranchTrueFalseTotal
if ($choice_score < 5 and $i > 0 and $i < $self->$#* and not $$self[$i - 1][0] and not $$self[$i + 1][0]) { } 4 24 28
elsif ($choice_score < 4 and $i > 0 and not $$self[$i - 1][0]) { } 2 22 24
elsif ($choice_score < 3 and $i < $self->$#* and not $$self[$i + 1][0]) { } 6 16 22
elsif ($choice_score < 2 and $i > 0 and $i < $self->$#*) { } 5 11 16
elsif ($choice_score < 1) { } 7 4 11
Condition91%11/12
$choice_score < 5 and $i > 0 and $i < $self->$#* and not $$self[$i - 1][0] and not $$self[$i + 1][0]
!ll&&!rl&&r
2314
$choice_score < 5 and $i > 0 and $i < $self->$#* and not $$self[$i - 1][0]
!ll&&!rl&&r
9145
$choice_score < 5 and $i > 0 and $i < $self->$#*
!ll&&!rl&&r
8119
$choice_score < 5 and $i > 0
!ll&&!rl&&r
0820
MC/DC80%4/5
$choice_score < 5 and $i > 0 and $i < $self->$#* and not $$self[$i - 1][0] and not $$self[$i + 1][0]
$choice_score < 5 $i > 0 $i < $self->$#* not $$self[$i - 1][0] not $$self[$i + 1][0]
Truth table83%5/6
A and B and C and not(D) and not(E)
A= $choice_score < 5B= $i > 0C= $i < $self->$#*D= not $$self[$i - 1][0]E= not $$self[$i + 1][0]
ABCDEresult
0XXXX0
10XXX0
110XX0
1110X0
111100
111111
141 4 $choice_score = 5;
142 4 $best_choice = $i;
143 4 last;
144 }
145  
146 ▶ elsif ($choice_score < 4 and $i > 0 and not $self->[$i - 1][0]) {
Condition83%5/6
$choice_score < 4 and $i > 0 and not $$self[$i - 1][0]
!ll&&!rl&&r
8142
$choice_score < 4 and $i > 0
!ll&&!rl&&r
0816
MC/DC66%2/3
$choice_score < 4 and $i > 0 and not $$self[$i - 1][0]
$choice_score < 4 $i > 0 not $$self[$i - 1][0]
Truth table75%3/4
A and B and not(C)
A= $choice_score < 4B= $i > 0C= not $$self[$i - 1][0]
ABCresult
0XX0
10X0
1100
1111
147 2 $choice_score = 4;
148 2 $best_choice = $i;
149 }
150  
151 ▶ elsif ($choice_score < 3 and $i < $#$self and not $self->[$i + 1][0]) {
Condition50%3/6
$choice_score < 3 and $i < $self->$#* and not $$self[$i + 1][0]
!ll&&!rl&&r
0166
$choice_score < 3 and $i < $self->$#*
!ll&&!rl&&r
0022
MC/DC33%1/3
$choice_score < 3 and $i < $self->$#* and not $$self[$i + 1][0]
$choice_score < 3 $i < $self->$#* not $$self[$i + 1][0]
Truth table50%2/4
A and B and not(C)
A= $choice_score < 3B= $i < $self->$#*C= not $$self[$i + 1][0]
ABCresult
0XX0
10X0
1100
1111
152 6 $choice_score = 3;
153 6 $best_choice = $i;
154 }
155  
156 ▶ elsif ($choice_score < 2 and $i > 0 and $i < $#$self) {
Condition83%5/6
$choice_score < 2 and $i > 0 and $i < $self->$#*
!ll&&!rl&&r
1105
$choice_score < 2 and $i > 0
!ll&&!rl&&r
475
MC/DC66%2/3
$choice_score < 2 and $i > 0 and $i < $self->$#*
$choice_score < 2 $i > 0 $i < $self->$#*
Truth table75%3/4
A and B and C
A= $choice_score < 2B= $i > 0C= $i < $self->$#*
ABCresult
0XX0
10X0
1100
1111
157 5 $choice_score = 2;
158 5 $best_choice = $i
159 }
160  
161 elsif ($choice_score < 1) {
162 7 $choice_score = 1;
163 7 $best_choice = $i;
164 }
165 }
166  
167 11 ▶ if (defined $best_choice) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $best_choice) 10 1 11
168 10 $self->[$best_choice][0] = 1;
169  
170 10 ▶ if (wantarray) {
Branch: 1 branch
BranchTrueFalseTotal
if (wantarray) { } 8 2 10
171 8 return ($best_choice, $self->[$best_choice][1], $choice_score);
172 }
173 else {
174 2 return $best_choice;
175 }
176 }
177  
178 1 return;
179 }
180  
181 =head2 pick
182  
183 my $resource = $self->pick($index);
184 my ($resource, $comfort_level) = $self->pick($index);
185  
186 Allows you to violate the usual algorithm to pick a urinal explicitly. In scalar
187 context it returns the resource picked. In list context, it returns that and the
188 comfort level your pick has. If the resource picked is already in use, an
189 exception will be thrown.
190  
191 =cut
192  
193 3 ▶sub pick {
Subroutine pick: called CC=3 SCAR=11.7
Pod documented
194 3 my ($self, $i) = @_;
195  
196 3 ▶ if ($self->[$i][0]) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->[$i][0]) 1 2 3
197 1 croak "The resource at index $i is already in use.";
198 }
199  
200 2 ▶ if (wantarray) {
Branch: 1 branch
BranchTrueFalseTotal
if (wantarray) { } 2 0 2
201 2 my @r = $self->look($i);
202 2 $self->[$i][0] = 1;
203 2 return @r;
204 }
205 else {
206 0 my $r = $self->look($i);
207 0 $self->[$i][0] = 1;
208 0 return $r;
209 }
210 }
211  
212 =head2 look
213  
214 my $resource = $self->look($index);
215 my ($resource, $comfort_level) = $self->look($index);
216  
217 In most algorithms, this would be called "peek," but peeking in urinals is, at
218 best, awkward and, at worst, likely to get you beat up.
219  
220 This is the same as L</pick>, but does not actually allocate. Also, the
221 C<$comfort_level> returned will be C<0> if the resource is currently in use.
222  
223 =cut
224  
225 5 ▶sub look {
Subroutine look: called CC=13 SCAR=27.3
Pod documented
226 5 my ($self, $i) = @_;
227  
228 5 ▶ if (wantarray) {
Branch: 1 branch
BranchTrueFalseTotal
if (wantarray) { } 4 1 5
229 4 my $choice_score = 0;
230 4 ▶ if (not $self->[$i][0]) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->[$i][0]) 3 1 4
231 3 ▶ if ($i > 0 and $i < $#$self and not $self->[$i - 1][0] and not $self->[$i + 1][0]) {
Branch: 4 branches
BranchTrueFalseTotal
if ($i > 0 and $i < $self->$#* and not $$self[$i - 1][0] and not $$self[$i + 1][0]) { } 1 2 3
elsif ($i > 0 and not $$self[$i - 1][0]) { } 0 2 2
elsif ($i < $self->$#* and not $$self[$i + 1][0]) { } 0 2 2
elsif ($i > 0 and $i < $self->$#*) { } 1 1 2
Condition77%7/9
$i > 0 and $i < $self->$#* and not $$self[$i - 1][0] and not $$self[$i + 1][0]
!ll&&!rl&&r
201
$i > 0 and $i < $self->$#* and not $$self[$i - 1][0]
!ll&&!rl&&r
111
$i > 0 and $i < $self->$#*
!ll&&!rl&&r
012
MC/DC50%2/4
$i > 0 and $i < $self->$#* and not $$self[$i - 1][0] and not $$self[$i + 1][0]
$i > 0 $i < $self->$#* not $$self[$i - 1][0] not $$self[$i + 1][0]
Truth table60%3/5
A and B and not(C) and not(D)
A= $i > 0B= $i < $self->$#*C= not $$self[$i - 1][0]D= not $$self[$i + 1][0]
ABCDresult
0XXX0
10XX0
110X0
11100
11111
232 1 $choice_score = 5;
233 }
234  
235 ▶ elsif ($i > 0 and not $self->[$i - 1][0]) {
Condition33%1/3
$i > 0 and not $$self[$i - 1][0]
!ll&&!rl&&r
020
MC/DC0%0/2
$i > 0 and not $$self[$i - 1][0]
$i > 0 not $$self[$i - 1][0]
Truth table33%1/3
A and not(B)
A= $i > 0B= not $$self[$i - 1][0]
ABresult
0X0
100
111
236 0 $choice_score = 4;
237 }
238  
239 ▶ elsif ($i < $#$self and not $self->[$i + 1][0]) {
Condition66%2/3
$i < $self->$#* and not $$self[$i + 1][0]
!ll&&!rl&&r
110
MC/DC0%0/2
$i < $self->$#* and not $$self[$i + 1][0]
$i < $self->$#* not $$self[$i + 1][0]
Truth table66%2/3
A and not(B)
A= $i < $self->$#*B= not $$self[$i + 1][0]
ABresult
0X0
100
111
240 0 $choice_score = 3;
241 }
242  
243 ▶ elsif ($i > 0 and $i < $#$self) {
Condition66%2/3
$i > 0 and $i < $self->$#*
!ll&&!rl&&r
011
MC/DC50%1/2
$i > 0 and $i < $self->$#*
$i > 0 $i < $self->$#*
Truth table66%2/3
A and B
A= $i > 0B= $i < $self->$#*
ABresult
0X0
100
111
244 1 $choice_score = 2;
245 }
246  
247 else {
248 1 $choice_score = 1;
249 }
250 }
251  
252 4 return ($self->[$i][1], $choice_score);
253 }
254 else {
255 1 return $self->[$i][1];
256 }
257 }
258  
259 =head2 leave
260  
261 $self->leave($index);
262  
263 Frees up the resource at the given index. Throws an exception if the resource is
264 not currently in use.
265  
266 =cut
267  
268 8 ▶sub leave {
Subroutine leave: called CC=2 SCAR=6.9
Pod documented
269 8 my ($self, $i) = @_;
270  
271 8 ▶ if (not $self->[$i][0]) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->[$i][0]) 1 7 8
272 1 croak "The resource at index $i is not currently in use.";
273 }
274  
275 7 $self->[$i][0] = 0;
276 7 return;
277 }
278  
279 =head1 AUTHOR
280  
281 Andrew Sterling Hanenkamp C<< hanenkamp@cpan.or >>
282  
283 =head1 COPYRIGHT & LICENSE
284  
285 Copyright 2014 Andrew Sterling Hanenkamp.
286  
287 This is free software and may be copied and distributed under the same terms as
288 Perl itself.
289  
290 =cut
291  
292 1 1;
↑ Summary