File Coverage

blib/lib/Adapter/Async/UnorderedMap.pm
Criterion Covered Total %
statement 9 18 50.0
branch 0 2 0.0
condition n/a
subroutine 3 7 42.8
pod 2 2 100.0
total 14 29 48.2


line stmt bran cond sub pod time code
1             package Adapter::Async::UnorderedMap;
2             $Adapter::Async::UnorderedMap::VERSION = '0.018';
3 2     2   1519 use strict;
  2         4  
  2         72  
4 2     2   9 use warnings;
  2         11  
  2         78  
5              
6 2     2   9 use parent qw(Adapter::Async);
  2         3  
  2         12  
7              
8             =head1 NAME
9              
10             Adapter::Async::UnorderedMap - API for dealing with key => value maps
11              
12             =head1 VERSION
13              
14             version 0.018
15              
16             =head1 DESCRIPTION
17              
18             =head2 Accessing data
19              
20             =over 4
21              
22             =item * count - resolves with the number of items. If this isn't possible, an estimate may be acceptable.
23              
24             say "items: " . $adapter->count->get
25              
26             =item * get - accepts a list of keys
27              
28             $adapter->get(
29             items => [1,2,3],
30             on_item => sub { ... }
31             )->on_done(sub { warn "all done, full list of items: %{$_[0]}" })
32              
33             Unlike the L method, this resolves to a hashref.
34              
35             The top-level of the hashref returned is guaranteed not to be modified further, if you want to store it
36             directly. No such guarantee applies to the values themselves - it is only a shallow clone.
37              
38             =back
39              
40             This means we have double-notify on get: a request for (a,b, 34, q) needs to fire events for each of a,b,34,q, and also return the hashref containing those keys on completion (by resolving a L).
41              
42             =head2 Modification
43              
44             =over 4
45              
46             =item * clear - remove all data
47              
48             =item * modify - changes a single entry
49              
50             =item * set - adds a new key
51              
52             =item * delete - removes an existing key
53              
54             =back
55              
56             =head2 Events
57              
58             All events are shared over a common bus for each data source, in the usual fashion - adapters and views can subscribe to the ones they're interested in, and publish events at any time.
59              
60             The adapter raises these:
61              
62             =over 4
63              
64             =item * item_changed - the given item has been modified. by default only applies to elements that were marked as visible.
65              
66             =item * splice - changes to the array which remove or add elements
67              
68             =item * move - an existing element moves to a new key (some adapters may not be able to differentiate between this and splice: if in doubt, use splice instead, don't report as a move unless it's guaranteed to be existing items)
69              
70             =back
71              
72             The view raises these:
73              
74             =over 4
75              
76             =item * visible - indicates visibility of one or more items. change events will start being sent for these items.
77              
78             visible => [1,2,3,4,5,6]
79              
80             Filters may result in a list with gaps:
81              
82             visible => [1,3,4,8,9,10]
83              
84             Note that "visible" means "the user is able to see this data", so they'd be a single page of data rather than the entire set when no filters are applied. Visibility changes often - scrolling will trigger a visible/hidden pair for example.
85              
86             Also note that ->get may be called on any element, regardless of visibility - prefetching is one common example here.
87              
88             =item * hidden - no longer visible.
89              
90             hidden => [1,2,4]
91              
92             =item * selected - this item is now part of an active selection. could be used to block deletes.
93              
94             selected => [1,4,5,6]
95              
96             =item * highlight - mouse over, cursor, etc.
97              
98             highlight => 1
99              
100             Some views won't raise this - if touch control is involved, for example
101              
102             =item * activate - some action has been performed.
103              
104             activate => [1]
105             activate => [1,2,5,6,7,8]
106              
107             Multi-activate will typically happen when items have been selected rather than just highlighted.
108              
109             The adapter itself doesn't do much with this.
110              
111             =back
112              
113             =cut
114              
115             =head1 METHODS
116              
117             =head2 set
118              
119             Sets the value of a key.
120              
121             $adapter->set(xyz => 'abc')
122              
123             =cut
124              
125 0     0 1   sub set { ... }
126              
127             =head2 all
128              
129             Returns all the items. Shortcut for calling
130             L then L.
131              
132             =cut
133              
134             sub all {
135 0     0 1   my ($self, %args) = @_;
136 0           my $f;
137             $f = $self->count->then(sub {
138 0     0     my ($count) = @_;
139 0 0         return Future->wrap([]) unless $count;
140 0           $self->get(
141             %args,
142             items => [0..$count-1],
143             )
144 0     0     })->on_ready(sub { undef $f });
  0            
145 0           $f
146             }
147              
148             1;
149              
150             __END__