1MCE::Shared::Minidb(3)User Contributed Perl DocumentationMCE::Shared::Minidb(3)
2
3
4

NAME

6       MCE::Shared::Minidb - A pure-Perl in-memory data store
7

VERSION

9       This document describes MCE::Shared::Minidb version 1.840
10

DESCRIPTION

12       A tiny in-memory NoSQL-like database for use as a standalone or managed
13       by MCE::Shared.
14
15       This module was created mainly for having an efficient manner in which
16       to manipulate hashes-of-hashes (HoH) and hashes-of-lists (HoA)
17       structures with MCE::Shared. An application may choose to use both
18       structures or one or the other. Internally, both structures reside in
19       memory simultaneously.
20
21        sub new {
22           # Dual top-level hashes: [ HoH, HoA ]
23           bless [
24              MCE::Shared::Ordhash->new(),  # Stores Hash-of-Hashes (HoH)
25              MCE::Shared::Ordhash->new(),  # Stores Hash-of-Lists  (HoA)
26           ], shift;
27        }
28
29        # each Ho(H) key => MCE::Shared::Hash->new()
30        # each Ho(A) key => MCE::Shared::Array->new()
31
32       Several methods described below may resemble the "Redis" API. It is not
33       the intent for this module to become 100% compatible.
34

SYNOPSIS

36        # non-shared or local construction for use by a single process
37
38        use MCE::Shared::Minidb;
39
40        my $db = MCE::Shared::Minidb->new();
41
42        # construction for sharing with other threads and processes
43
44        use MCE::Shared;
45
46        my $db = MCE::Shared->minidb();
47
48        # Hash of Hashes (HoH)
49        # Update the hash stored at key1/key2
50
51        $db->hset( "key1", "f1", "foo" );
52        $db->hset( "key2", "f1", "bar", "f2", "baz" );
53
54        $val = $db->hget( "key2", "f2" );  # "baz"
55
56        # Hash of Lists (HoA)
57        # Update the list stored at key1/key2
58
59        $db->lset( "key1", 0, "foo" );
60        $db->lset( "key2", 0, "bar", 1, "baz" );
61
62        $val = $db->lget( "key2", 1 );     # "baz"
63
64        # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
65
66        $db->pipeline(
67           [ "lset", "key1", 0, "foo" ],
68           [ "hset", "key1", "field1", "foo" ],
69           [ "lset", "key2", 0, "bar", 1, "baz" ],
70           [ "hset", "key2", "field1", "bar", "field2", "baz" ]
71        );
72

SYNTAX for QUERY STRING

74       Several methods take a query string for an argument. The format of the
75       string is described below. In the context of sharing, the query
76       mechanism is beneficial for the shared-manager process. It is able to
77       perform the query where the data resides versus the client-process grep
78       locally involving lots of IPC.
79
80        o Basic demonstration
81
82          # query the hash stored at "some key"
83          @keys = $db->hkeys( "some key", "query string given here" );
84          @keys = $db->hkeys( "some key", "val =~ /pattern/" );
85
86          # query the top-level hash (H)oH
87          @keys = $db->hkeys( "query string given here" );
88          @keys = $db->hkeys( "key =~ /pattern/" );
89
90        o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
91        o Multiple expressions delimited by :AND or :OR, mixed case allowed
92
93          "key eq 'some key' :or (field > 5 :and field < 9)"
94          "key eq some key :or (field > 5 :and field < 9)"
95          "key =~ /pattern/i :And field =~ /pattern/i"   # HoH
96          "key =~ /pattern/i :And index =~ /pattern/i"   # HoA
97          "index eq foo baz :OR key !~ /pattern/i"       # e.g. 9 eq "foo baz"
98
99          * key   matches on primary keys in the hash (H)oH or (H)oA
100          * field matches on HoH->{key}{field} e.g. address
101          * index matches on HoA->{key}[index] e.g. 9
102
103        o Quoting is optional inside the string
104        o Primary keys (H)oH may have spaces, but not so for field_names
105
106          "key =~ /pattern/i :AND field eq 'foo bar'"    # address eq "foo bar"
107          "key =~ /pattern/i :AND field eq foo bar"      # address eq "foo bar"
108
109          "key =~ 'some key' :AND 'some_field' eq 'foo bar'"  # ok: some_field
110          "key =~ some key :AND some_field eq foo bar"
111
112          "key =~ 'some key' :AND 'some field' eq 'foo bar'"  # fail: some field
113          "key =~ some key :AND some field eq foo bar"
114
115       Examples.
116
117        # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
118        # key/val means to match against actual key/val respectively
119
120        # a query made to a hash stored at "some key"
121        # note that "fieldNames" must not have spaces
122
123          @keys  = $db->hkeys(
124             "some key", "key eq some_field :or (val > 5 :and val < 9)"
125          );
126
127        # queries made to a list stored at "some key"
128
129          @pairs = $db->lpairs( "some key", "key >= 50 :AND val =~ /sun|moon/" );
130          @pairs = $db->lpairs( "some key", "val eq sun :OR val eq moon" );
131
132        # the key modifier is the only thing possible for top-level queries
133        # reason: value equals a hash or list reference containing 2nd-level data
134
135          @keys  = $db->hkeys( "key eq 'some key'" );
136          @keys  = $db->hkeys( "key eq some key" );
137
138          @keys  = $db->hkeys( "key =~ /$pattern/i" );
139          @keys  = $db->hkeys( "key !~ /$pattern/i" );
140
141          %pairs = $db->hpairs( "key == $number" );
142          %pairs = $db->hpairs( "key != $number" );
143          %pairs = $db->hpairs( "key <  $number :or key > $number" );
144          %pairs = $db->hpairs( "key <= $number" );
145          %pairs = $db->hpairs( "key >  $number" );
146          %pairs = $db->hpairs( "key >= $number" );
147
148          @vals  = $db->hvals( "key eq $string" );
149          @vals  = $db->hvals( "key ne $string with space" );
150          @vals  = $db->hvals( "key lt $string :or key =~ /$pat1|$pat2/" );
151          @vals  = $db->hvals( "key le $string :or key eq 'foo bar'" );
152          @vals  = $db->hvals( "key le $string :or key eq foo bar" );
153          @vals  = $db->hvals( "key gt $string" );
154          @vals  = $db->hvals( "key ge $string" );
155
156        # see select_aref and select_href below for db-like queries against
157        # the underlying Ho(A) and Ho(H) structures respectively
158

API DOCUMENTATION - DB

160       new
161          Constructs an empty in-memory "HoH" and "HoA" key-store database
162          structure.
163
164           # non-shared or local construction for use by a single process
165
166           use MCE::Shared::Minidb;
167
168           $db = MCE::Shared::Minidb->new();
169
170           # construction for sharing with other threads and processes
171
172           use MCE::Shared;
173
174           $db = MCE::Shared->minidb();
175
176       dump ( "file.dat" )
177          Dumps the in-memory content to a file.
178
179           $db->dump( "content.dat" );
180
181       pipeline ( [ func1, @args ], [ func2, @args ], ... )
182          Combines multiple commands for the object to be processed serially.
183          For shared objects, the call is made atomically due to single IPC to
184          the shared-manager process. The "pipeline" method is fully
185          "wantarray"-aware and receives a list of commands and their
186          arguments. In scalar or list context, it returns data from the last
187          command in the pipeline.
188
189           @vals = $db->pipeline(                     # ( "bar", "baz" )
190              [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
191              [ "hget", "some_key", "f1", "f2" ]
192           );
193
194           $len = $db->pipeline(                      # 2, same as $db->hlen("key2)
195              [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
196              [ "hlen", "some_key" ]
197           );
198
199           $db->pipeline(
200              [ "lset", "key1", 0, "foo" ],
201              [ "hset", "key1", "field1", "foo" ],
202              [ "lset", "key2", 0, "bar", 1, "baz" ],
203              [ "hset", "key2", "field1", "bar", "field2", "baz" ]
204           );
205
206          Current API available since 1.809.
207
208       pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
209          Same as "pipeline", but returns data for every command in the
210          pipeline.
211
212           @vals = $db->pipeline_ex(                  # ( "bar", "baz" )
213              [ "hset", "key3", "field1", "bar" ],
214              [ "hset", "key3", "field2", "baz" ]
215           );
216
217           $chunk_size = 3;
218
219           $db->hset("some_key", chunk_id => 0);
220           $db->lassign("some_key", @ARGV);
221
222           while (1) {
223              ($chunk_id, @next) = $db->pipeline_ex(
224                 [ "hincr",   "some_key", "chunk_id"     ],
225                 [ "lsplice", "some_key", 0, $chunk_size ]
226              );
227
228              last unless @next;
229
230              ...
231           }
232
233          Current API available since 1.809.
234
235       restore ( "file.dat" )
236          Restores the in-memory content from a file.
237
238           $db->restore( "content.dat" );
239
240       select_aref ( ":hashes", "select string" )
241       select_href ( ":hashes", "select string" )
242          Returns a list containing "[ key, aref ]" pairs or "[ key, href ]"
243          pairs from the hash of hashes (HoH).
244
245          The "select_aref" and "select_href" methods take a select string
246          supporting field names and optionally sort modifiers. The syntax for
247          the query string, between ":WHERE" and ":ORDER BY", is the same as
248          described above.
249
250          The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC",
251          and "ALPHA" may be mixed case. e.g. ":Where"
252
253          HoH select string:
254
255           "f1 f2 f3 :WHERE f4 > 20 :AND key =~ /foo/ :ORDER BY f5 DESC ALPHA"
256           "f5 f1 f2 :WHERE fN > 40 :AND key =~ /bar/ :ORDER BY key ALPHA"
257           "f5 f1 f2 :WHERE fN > 40 :AND key =~ /bar/"
258           "f5 f1 f2"
259
260           * key matches on keys stored in the primary level hash (H)oH
261
262          HoH select synopsis:
263
264           @rows = $db->select_aref( ":hashes", "some_field :ORDER BY some_field" );
265           @rows = $db->select_aref( ":hashes", "f2 f6 f5 :ORDER BY f4" );
266
267           # $rows[0] = [ "key1", [ "f2_val", "f6_val", "f5_val" ] ]
268           # $rows[1] = [ "key2", [ "f2_val", "f6_val", "f5_val" ] ]
269           # $rows[2] = [ "key3", [ "f2_val", "f6_val", "f5_val" ] ]
270           # ...
271           # $rows[N] = [ "keyN", [ "f2_val", "f6_val", "f5_val" ] ]
272
273           @rows = $db->select_href( ":hashes", "some_field :ORDER BY some_field" );
274           @rows = $db->select_href( ":hashes", "f2 f6 f5 :ORDER BY f4" );
275
276           # $rows[0] = [ "key1", { f2 => "val", f6 => "val", f5 => "val" } ]
277           # $rows[1] = [ "key2", { f2 => "val", f6 => "val", f5 => "val" } ]
278           # $rows[2] = [ "key3", { f2 => "val", f6 => "val", f5 => "val" } ]
279           # ...
280           # $rows[N] = [ "keyN", { f2 => "val", f6 => "val", f5 => "val" } ]
281
282       select_aref ( ":lists", "select string" )
283       select_href ( ":lists", "select string" )
284          Returns a list containing "[ key, aref ]" pairs or "[ key, href ]"
285          pairs from the hash of lists (HoA).
286
287          The "select_aref" and "select_href" methods take a select string
288          supporting field indices and optionally sort modifiers. The syntax
289          for the query string, between ":WHERE" and ":ORDER BY", is the same
290          as described above.
291
292          The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC",
293          and "ALPHA" may be mixed case. e.g. ":Where"
294
295          HoA select string:
296
297           "17 15 11 :WHERE 12 > 20 :AND key =~ /foo/ :ORDER BY 10 DESC ALPHA"
298           "17 15 11 :WHERE 12 > 40 :AND key =~ /bar/ :ORDER BY key ALPHA"
299           "17 15 11 :WHERE 12 > 40 :AND key =~ /bar/"
300           "17 15 11"
301
302           * key matches on keys stored in the primary level hash (H)oA
303           * above, list indices are given as 17, 15, 11, 12, and 10
304           * the shorter form is allowed e.g. "4 > 20 :AND key =~ /baz/"
305
306          HoA select synopsis:
307
308           @rows = $db->select_aref( ":lists", "some_index :ORDER BY some_index" );
309           @rows = $db->select_aref( ":lists", "2 6 5 :ORDER BY 4" );
310
311           # $rows[0] = [ "key1", [ "2_val", "6_val", "5_val" ] ]
312           # $rows[1] = [ "key2", [ "2_val", "6_val", "5_val" ] ]
313           # $rows[2] = [ "key3", [ "2_val", "6_val", "5_val" ] ]
314           # ...
315           # $rows[N] = [ "keyN", [ "2_val", "6_val", "5_val" ] ]
316
317           @rows = $db->select_href( ":lists", "some_index :ORDER BY some_index" );
318           @rows = $db->select_href( ":lists", "2 6 5 :ORDER BY 4" );
319
320           # $rows[0] = [ "key1", { 2 => "val", 6 => "val", 5 => "val" } ]
321           # $rows[1] = [ "key2", { 2 => "val", 6 => "val", 5 => "val" } ]
322           # $rows[2] = [ "key3", { 2 => "val", 6 => "val", 5 => "val" } ]
323           # ...
324           # $rows[N] = [ "keyN", { 2 => "val", 6 => "val", 5 => "val" } ]
325

API DOCUMENTATION - HASHES ( HoH )

327       hassign ( key, field, value [, field, value, ... ] )
328          Clears the hash stored at key, then sets the value of a hash field
329          and returns its new value. Multiple field_value pairs may be set at
330          once. In that case, the number of fields is returned. This is
331          equivalent to "hclear", "hset".
332
333           $val = $db->hassign( "some_key", "field", "value" );
334           $len = $db->hassign( "some_key", "f1" => "val1", "f2" => "val2" );
335
336          API available since 1.007.
337
338       hclear ( key )
339          Removes all key-value pairs from the first level hash (H)oH when no
340          arguments are given. Otherwise, removes all field-value pairs stored
341          at key.
342
343           $db->hclear;
344           $db->hclear( "some_key" );
345
346       hdel ( key, field [, field, ... ] )
347          Deletes one or more hash fields. It returns the value associated
348          with the field if a single field is given. Otherwise, it returns the
349          number of fields actually removed from the hash stored at key. A
350          field which does not exist in the hash is not counted.
351
352           $val = $db->hdel( "some_key", "some_field" );
353           $cnt = $db->hdel( "some_key", "field1", "field2" );
354
355       hdel ( key )
356          Deletes and returns the "MCE::Shared::Hash" object stored at key or
357          "undef" if the key does not exists in the first level hash (H)oH.
358
359           $ha_obj = $db->hdel( "some_key" );
360
361       hexists ( key, field [, field, ... ] )
362          Determines if a hash field exists. For multiple fields, a truth
363          value is returned only if all given fields exist in the hash stored
364          at key.
365
366           if ( $db->hexists( "some_key", "some_field" ) ) { ... }
367           if ( $db->hexists( "some_key", "f1", "f5" ) ) { ... }
368
369       hexists ( key )
370          Determines if a key exists in the first level hash (H)oH.
371
372           if ( $db->hexists( "some_key" ) ) { ... }
373
374       hget ( key, field [, field, ... ] )
375          Gets the values of all given hash fields. The "undef" value is
376          returned for fields which do not exists in the hash stored at key.
377          Likewise, the "undef" value is returned if the key does not exists
378          in the first level hash (H)oH.
379
380           $val = $db->hget( "some_key", "field" );
381
382           ( $val1, $val2 ) = $db->hget( "some_key", "field1", "field2" );
383
384       hget ( key )
385          Gets the "MCE::Shared::Hash" object for the hash stored at key or
386          "undef" if the key does not exists in the first level hash (H)oH.
387
388           $ha_obj = $db->hget( "some_key" );
389
390       hkeys ( key, [ field [, field, ... ] ] )
391          Returns keys stored in the first level hash (H)oH when no arguments
392          are given.  Otherwise, returns the given fields in the hash stored
393          at key. Fields that do not exist will have the "undef" value. In
394          scalar context, returns the size of the object, either the hash
395          stored at key or the first level hash.
396
397           @keys   = $db->hkeys;
398           @fields = $db->hkeys( "some_key" );
399           @fields = $db->hkeys( "some_key", "field1", "field2" );
400           $len    = $db->hkeys( "some_key" );
401           $len    = $db->hkeys;
402
403       hkeys ( key, "query string" )
404          Returns only fields stored at key that match the given criteria. It
405          returns an empty list if the search found nothing. The syntax for
406          the "query string" is described above. In scalar context, returns
407          the size of the resulting list.
408
409           @keys = $db->hkeys( "some_key", "val eq some_value" );
410           @keys = $db->hkeys( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
411           @keys = $db->hkeys( "some_key", "val eq sun :OR val eq moon );
412           $len  = $db->hkeys( "some_key", "key =~ /$pattern/" );
413
414       hkeys ( "query string" )
415          For the one argument form, the search is applied to keys stored in
416          the primary hash only (H)oH. Therefore, the "key" modifier is the
417          only thing possible if wanting any result.
418
419           @keys = $db->hkeys( "key =~ /$pattern/" );
420           $len  = $db->hkeys( "key =~ /$pattern/" );
421
422       hlen ( key [, field ] )
423          Returns the size of the first level hash (H)oH when no arguments are
424          given.  For the given key, returns the size of hash stored at key or
425          optionally, the length of the value stored at key-field. It returns
426          the "undef" value if either the given key or given field does not
427          exists.
428
429           $len = $db->hlen;
430           $len = $db->hlen( $key );
431           $len = $db->hlen( $key, $field );
432
433       hpairs ( key, [ field [, field, ... ] ] )
434          Returns key-value pairs stored in the first level hash (H)oH when no
435          arguments are given. Otherwise, returns field-value pairs for the
436          given fields in the hash stored at key. Fields that do not exist
437          will have the "undef" value. In scalar context, returns the size of
438          the object, either the hash stored at key or the first level hash.
439
440           @pairs = $db->hpairs;                 # ( key => href, ... )
441           @pairs = $db->hpairs( "some_key" );   # ( field => value, ... )
442           @pairs = $db->hpairs( "some_key", "field1", "field2" );
443           $len   = $db->hpairs( "some_key" );
444           $len   = $db->hpairs;
445
446       hpairs ( key, "query string" )
447          Returns only field-value pairs stored at key that match the given
448          criteria.  It returns an empty list if the search found nothing. The
449          syntax for the "query string" is described above. In scalar context,
450          returns the size of the resulting list.
451
452           @pairs = $db->hpairs( "some_key", "val eq some_value" );
453           @pairs = $db->hpairs( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
454           @pairs = $db->hpairs( "some_key", "val eq sun :OR val eq moon" );
455           $len   = $db->hpairs( "some_key", "key =~ /$pattern/" );
456
457       hpairs ( "query string" )
458          For the one argument form, the search is applied to keys stored in
459          the primary hash only (H)oH. Therefore, the "key" modifier is the
460          only thing possible if wanting any result.
461
462           @keys = $db->hpairs( "key =~ /$pattern/" );
463           $len  = $db->hpairs( "key =~ /$pattern/" );
464
465       hset ( key, field, value [, field, value, ... ] )
466          Sets the value of a hash field and returns its new value. Multiple
467          field_value pairs may be set at once. In that case, the number of
468          fields stored at key is returned.
469
470           $val = $db->hset( "some_key", "field", "value" );
471           $len = $db->hset( "some_key", "f1" => "val1", "f2" => "val2" );
472
473       hshift
474          Removes and returns the first key-value pair or value in scalar
475          context from the first-level hash (H)oH. If the "HASH" is empty,
476          returns the undefined value.
477
478           ( $key, $href ) = $db->hshift;
479
480           $href = $db->hshift;
481
482       hsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
483       hsort ( "BY field [ ASC | DESC ] [ ALPHA ]" )
484          Returns sorted keys from the first level hash (H)oH, leaving the
485          elements intact. In void context, sorts the first level hash in-
486          place. Sorting is numeric by default.
487
488           @keys = $db->hsort( "BY key" );
489           @keys = $db->hsort( "BY some_field" );
490
491           $db->hsort( "BY key" );
492           $db->hsort( "BY some_field" );
493
494          If the keys or field values contain string values and you want to
495          sort them lexicographically, specify the "ALPHA" modifier.
496
497           @keys = $db->hsort( "BY key ALPHA" );
498           @keys = $db->hsort( "BY some_field ALPHA" );
499
500           $db->hsort( "BY key ALPHA" );
501           $db->hsort( "BY some_field ALPHA" );
502
503          The default is "ASC" for sorting the elements from small to large.
504          In order to sort from large to small, specify the "DESC" modifier.
505
506           @keys = $db->hsort( "BY key DESC ALPHA" );
507           @keys = $db->hsort( "BY some_field DESC ALPHA" );
508
509           $db->hsort( "BY key DESC ALPHA" );
510           $db->hsort( "BY some_field DESC ALPHA" );
511
512       hvals ( key, [ field [, field, ... ] ] )
513          Returns values stored in the first level hash (H)oH when no
514          arguments are given.  Otherwise, returns values for the given fields
515          in the hash stored at key. Fields that do not exist will have the
516          "undef" value. In scalar context, returns the size of the object,
517          either the hash stored at key or the first level hash.
518
519           @hrefs = $db->hvals;
520           @vals  = $db->hvals( "some_key" );
521           @vals  = $db->hvals( "some_key", "field1", "field2" );
522           $len   = $db->hvals( "some_key" );
523           $len   = $db->hvals;
524
525       hvals ( key, "query string" )
526          Returns only values stored at key that match the given criteria. It
527          returns an empty list if the search found nothing. The syntax for
528          the "query string" is described above. In scalar context, returns
529          the size of the resulting list.
530
531           @vals = $db->hvals( "some_key", "val eq some_value" );
532           @vals = $db->hvals( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
533           @vals = $db->hvals( "some_key", "val eq sun :OR val eq moon" );
534           $len  = $db->hvals( "some_key", "key =~ /$pattern/" );
535
536       hvals ( "query string" )
537          For the one argument form, the search is applied to keys stored in
538          the primary hash only (H)oH. Therefore, the "key" modifier is the
539          only thing possible if wanting any result.
540
541           @keys = $db->hvals( "key =~ /$pattern/" );
542           $len  = $db->hvals( "key =~ /$pattern/" );
543

SUGAR METHODS - HASHES ( HoH )

545       This module is equipped with sugar methods to not have to call "set"
546       and "get" explicitly. In shared context, the benefit is atomicity and
547       reduction in inter-process communication.
548
549       happend ( key, field, string )
550          Appends a value to key-field and returns its new length.
551
552           $len = $db->happend( $key, $field, "foo" );
553
554       hdecr ( key, field )
555          Decrements the value of key-field by one and returns its new value.
556
557           $num = $db->hdecr( $key, $field );
558
559       hdecrby ( key, field, number )
560          Decrements the value of key-field by the given number and returns
561          its new value.
562
563           $num = $db->hdecrby( $key, $field, 2 );
564
565       hgetdecr ( key, field )
566          Decrements the value of key-field by one and returns its old value.
567
568           $old = $db->hgetdecr( $key, $field );
569
570       hgetincr ( key, field )
571          Increments the value of key-field by one and returns its old value.
572
573           $old = $db->hgetincr( $key, $field );
574
575       hgetset ( key, field, value )
576          Sets the value of key-field and returns its old value.
577
578           $old = $db->hgetset( $key, $field, "baz" );
579
580       hincr ( key, field )
581          Increments the value of key-field by one and returns its new value.
582
583           $num = $db->hincr( $key, $field );
584
585       hincrby ( key, field, number )
586          Increments the value of key-field by the given number and returns
587          its new value.
588
589           $num = $db->hincrby( $key, $field, 2 );
590

API DOCUMENTATION - LISTS ( HoA )

592       lassign ( key, value [, value, ... ] )
593          Clears the list stored at key, then prepends one or multiple values
594          and returns the new length. This is equivalent to "lclear", "lpush".
595
596           $len = $db->lassign( "some_key", "val1", "val2" );
597
598          API available since 1.007.
599
600       lclear ( key )
601          Removes all key-value pairs from the first level hash (H)oA when no
602          arguments are given. Otherwise, removes all elements from the list
603          stored at key.
604
605           $db->lclear;
606           $db->lclear( "some_key" );
607
608       ldel ( key, index [, index, ... ] )
609          Deletes one or more elements by their indices. It returns the value
610          associated with the index if a single index is given. Otherwise, it
611          returns the number of elements actually removed from the list stored
612          at key. An index which does not exists in the list is not counted.
613
614           $val = $db->ldel( "some_key", 20 );
615           $cnt = $db->ldel( "some_key", 0, 1 );
616
617       ldel ( key )
618          Deletes and returns the "MCE::Shared::Array" object stored at key or
619          "undef" if the key does not exists in the first level hash (H)oA.
620
621           $ar_obj = $db->ldel( "some_key" );
622
623       lexists ( key, index [, index, ... ] )
624          Determines if elements by their indices exist in the list. For
625          multiple indices, a truth value is returned only if all given
626          indices exist in the list stored at key. The behavior is strongly
627          tied to the use of delete on lists.
628
629           $db->lset( "some_key", 0, "value0" );
630           $db->lset( "some_key", 1, "value1" );
631           $db->lset( "some_key", 2, "value2" );
632           $db->lset( "some_key", 3, "value3" );
633
634           $db->lexists( "some_key", 2 );     # True
635           $db->lexists( "some_key", 2, 3 );  # True
636           $db->ldel   ( "some_key", 2 );     # value2
637
638           $db->lexists( "some_key", 2 );     # False
639           $db->lexists( "some_key", 2, 3 );  # False
640           $db->lexists( "some_key", 3 );     # True
641
642       lexists ( key )
643          Determines if a key exists in the first level hash (H)oA.
644
645           if ( $db->lexists( "some_key" ) ) { ... }
646
647       lget ( key, index [, index, ... ] )
648          Gets the values of all given list indices. The "undef" value is
649          returned for indices which do not exists in the list stored at key.
650          Likewise, the "undef" value is returned if the key does not exists
651          in the first level hash (H)oA.
652
653           $val = $db->lget( "some_key", 20 );
654
655           ( $val1, $val2 ) = $db->lget( "some_key", 0, 1 );
656
657       lget ( key )
658          Gets the "MCE::Shared::Array" object for the list stored at key or
659          "undef" if the key does not exists in the first level hash (H)oA.
660
661           $ar_obj = $db->lget( "some_key" );
662
663       lkeys ( key, [ index [, index, ... ] ] )
664          Returns keys stored in the first level hash (H)oA when no arguments
665          are given.  Otherwise, returns the given indices in the list stored
666          at key. Indices that do not exist will have the "undef" value. In
667          scalar context, returns the size of the object, either the list
668          stored at key or the first level hash.
669
670           @keys    = $db->lkeys;
671           @indices = $db->lkeys( "some_key" );
672           @indices = $db->lkeys( "some_key", 0, 1 );
673           $len     = $db->lkeys( "some_key" );
674           $len     = $db->lkeys;
675
676       lkeys ( key, "query string" )
677          Returns only indices stored at key that match the given criteria. It
678          returns an empty list if the search found nothing. The syntax for
679          the "query string" is described above. In scalar context, returns
680          the size of the resulting list.
681
682           @keys = $db->lkeys( "some_key", "val eq some_value" );
683           @keys = $db->lkeys( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
684           @keys = $db->lkeys( "some_key", "val eq sun :OR val eq moon" );
685           $len  = $db->lkeys( "some_key", "key =~ /$pattern/" );
686
687       lkeys ( "query string" )
688          For the one argument form, the search is applied to keys stored in
689          the primary hash only (H)oA. Therefore, the "key" modifier is the
690          only thing possible if wanting any result.
691
692           @keys = $db->lkeys( "key =~ /$pattern/" );
693           $len  = $db->lkeys( "key =~ /$pattern/" );
694
695       llen ( key [, index ] )
696          Returns the size of the first level hash (H)oA when no arguments are
697          given.  For the given index, returns the size of list stored at key
698          or optionally, the length of the value stored at key-index. It
699          returns the "undef" value if either the given key or given index
700          does not exists.
701
702           $len = $db->llen;
703           $len = $db->llen( $key );
704           $len = $db->llen( $key, 0 );
705
706       lpairs ( key, [ index [, index, ... ] ] )
707          Returns key-value pairs stored in the first level hash (H)oA when no
708          arguments are given. Otherwise, returns index-value pairs for the
709          given indices in the list stored at key. Indices that do not exist
710          will have the "undef" value.  In scalar context, returns the size of
711          the object, either the list stored at key or the first level hash.
712
713           @pairs = $db->lpairs;                 # ( key => aref, ... )
714           @pairs = $db->lpairs( "some_key" );   # ( index => value, ... )
715           @pairs = $db->lpairs( "some_key", 0, 1 );
716           $len   = $db->lpairs( "some_key" );
717           $len   = $db->lpairs;
718
719       lpairs ( key, "query string" )
720          Returns only index-value pairs stored at key that match the given
721          criteria.  It returns an empty list if the search found nothing. The
722          syntax for the "query string" is described above. In scalar context,
723          returns the size of the resulting list.
724
725           @pairs = $db->lpairs( "some_key", "val eq some_value" );
726           @pairs = $db->lpairs( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
727           @pairs = $db->lpairs( "some_key", "val eq sun :OR val eq moon" );
728           $len   = $db->lpairs( "some_key", "key =~ /$pattern/" );
729
730       lpairs ( "query string" )
731          For the one argument form, the search is applied to keys stored in
732          the primary hash only (H)oA. Therefore, the "key" modifier is the
733          only thing possible if wanting any result.
734
735           @keys = $db->lpairs( "key =~ /$pattern/" );
736           $len  = $db->lpairs( "key =~ /$pattern/" );
737
738       lpop ( key )
739          Removes and returns the first value of the list stored at key. If
740          there are no elements in the list, returns the undefined value.
741
742           $val = $db->lpop( $key );
743
744       lpush ( key, value [, value, ... ] )
745          Prepends one or multiple values to the head of the list stored at
746          key and returns the new length.
747
748           $len = $db->lpush( "some_key", "val1", "val2" );
749
750       lrange ( key, start, stop )
751          Returns the specified elements of the list stored at key. The
752          offsets "start" and "stop" can also be negative numbers indicating
753          offsets starting at the end of the list.
754
755          An empty list is returned if "start" is larger than the end of the
756          list.  "stop" is set to the last index of the list if larger than
757          the actual end of the list.
758
759           @list = $db->lrange( "some_key", 20, 29 );
760           @list = $db->lrange( "some_key", -4, -1 );
761
762       lset ( key, index, value [, index, value, ... ] )
763          Sets the value of an element in a list by its index and returns its
764          new value.  Multiple index_value pairs may be set all at once. In
765          that case, the length of the list is returned.
766
767           $val = $db->lset( "some_key", 2, "value" );
768           $len = $db->lset( "some_key", 0 => "val1", 1 => "val2" );
769
770       lshift
771          Removes and returns the first key-value pair or value in scalar
772          context from the first-level hash (H)oA. If the "HASH" is empty,
773          returns the undefined value. See "lpop" to shift the first value of
774          the list stored at key.
775
776           ( $key, $aref ) = $db->lshift;
777
778           $aref = $db->lshift;
779
780       lsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
781       lsort ( "BY index [ ASC | DESC ] [ ALPHA ]" )
782          Returns sorted keys from the first level hash (H)oA, leaving the
783          elements intact. In void context, sorts the first level hash in-
784          place. Sorting is numeric by default.
785
786           @keys = $db->lsort( "BY key" );
787           @keys = $db->lsort( "BY some_index" );
788
789           $db->lsort( "BY key" );
790           $db->lsort( "BY some_index" );
791
792          If the keys or field values given by index contain string values and
793          you want to sort them lexicographically, specify the "ALPHA"
794          modifier.
795
796           @keys = $db->lsort( "BY key ALPHA" );
797           @keys = $db->lsort( "BY some_index ALPHA" );
798
799           $db->lsort( "BY key ALPHA" );
800           $db->lsort( "BY some_index ALPHA" );
801
802          The default is "ASC" for sorting the elements from small to large.
803          In order to sort from large to small, specify the "DESC" modifier.
804
805           @keys = $db->lsort( "BY key DESC ALPHA" );
806           @keys = $db->lsort( "BY some_index DESC ALPHA" );
807
808           $db->lsort( "BY key DESC ALPHA" );
809           $db->lsort( "BY some_index DESC ALPHA" );
810
811       lsort ( key, "BY key [ ASC | DESC ] [ ALPHA ]" )
812       lsort ( key, "BY val [ ASC | DESC ] [ ALPHA ]" )
813          The two argument form has similar functionality. Here, sorting is
814          applied to the list stored at key. For example, the following
815          reverses the list stored at the given key. The "BY key" modifier
816          refers to the indices in the list and not the values.
817
818           $db->lsort( "some_key", "BY key DESC" );
819
820       lsplice ( key, offset [, length [, list ] ] )
821          Removes the elements designated by "offset" and "length" from the
822          array stored at key, and replaces them with the elements of "list",
823          if any.  The behavior is similar to the Perl "splice" function.
824
825           @items = $db->lsplice( "some_key", 20, 2, @list );
826           @items = $db->lsplice( "some_key", 20, 2 );
827           @items = $db->lsplice( "some_key", 20 );
828
829       lvals ( key, [ index [, index, ... ] ] )
830          Returns values stored in the first level hash (H)oA when no
831          arguments are given. Otherwise, returns values for the given indices
832          in the list stored at key. Indices that do not exist will have the
833          "undef" value. In scalar context, returns the size of the object,
834          either the list stored at key or the first level hash.
835
836           @arefs = $db->lvals;
837           @vals  = $db->lvals( "some_key" );
838           @vals  = $db->lvals( "some_key", 0, 1 );
839           $len   = $db->lvals( "some_key" );
840           $len   = $db->lvals;
841
842       lvals ( key, "query string" )
843          Returns only values stored at key that match the given criteria. It
844          returns an empty list if the search found nothing. The syntax for
845          the "query string" is described above. In scalar context, returns
846          the size of the resulting list.
847
848           @keys = $db->lvals( "some_key", "val eq some_value" );
849           @keys = $db->lvals( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
850           @keys = $db->lvals( "some_key", "val eq sun :OR val eq moon" );
851           $len  = $db->lvals( "some_key", "key =~ /$pattern/" );
852
853       lvals ( "query string" )
854          For the one argument form, the search is applied to keys stored in
855          the primary hash only (H)oA. Therefore, the "key" modifier is the
856          only thing possible if wanting any result.
857
858           @keys = $db->lvals( "key =~ /$pattern/" );
859           $len  = $db->lvals( "key =~ /$pattern/" );
860
861       rpop ( key )
862          Removes and returns the last value of the list stored at key. If
863          there are no elements in the list, returns the undefined value.
864
865           $val = $db->rpop( $key );
866
867       rpush ( key, value [, value, ... ] )
868          Appends one or multiple values to the tail of the list stored at key
869          and returns the new length.
870
871           $len = $db->rpush( "some_key", "val1", "val2" );
872

SUGAR METHODS - LISTS ( HoA )

874       This module is equipped with sugar methods to not have to call "set"
875       and "get" explicitly. In shared context, the benefit is atomicity and
876       reduction in inter-process communication.
877
878       lappend ( key, index, string )
879          Appends a value to key-index and returns its new length.
880
881           $len = $db->lappend( $key, 0, "foo" );
882
883       ldecr ( key, index )
884          Decrements the value of key-index by one and returns its new value.
885
886           $num = $db->ldecr( $key, 0 );
887
888       ldecrby ( key, index, number )
889          Decrements the value of key-index by the given number and returns
890          its new value.
891
892           $num = $db->ldecrby( $key, 0, 2 );
893
894       lgetdecr ( key, index )
895          Decrements the value of key-index by one and returns its old value.
896
897           $old = $db->lgetdecr( $key, 0 );
898
899       lgetincr ( key, index )
900          Increments the value of key-index by one and returns its old value.
901
902           $old = $db->lgetincr( $key, 0 );
903
904       lgetset ( key, index, value )
905          Sets the value of key-index and return its old value.
906
907           $old = $db->lgetset( $key, 0, "baz" );
908
909       lincr ( key, index )
910          Increments the value of key-index by one and returns its new value.
911
912           $num = $db->lincr( $key, 0 );
913
914       lincrby ( key, index, number )
915          Increments the value of key-index by the given number and returns
916          its new value.
917
918           $num = $db->lincrby( $key, 0, 2 );
919

CREDITS

921       The implementation is inspired by various Redis Hash/List primitives at
922       <http://redis.io/commands>.
923

INDEX

925       MCE, MCE::Hobo, MCE::Shared
926

AUTHOR

928       Mario E. Roy, <marioeroy AT gmail DOT com>
929
930
931
932perl v5.28.1                      2019-01-04            MCE::Shared::Minidb(3)
Impressum