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.862
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   MCE::Shared::Minidb->new ()
161   MCE::Shared->minidb ()
162       Constructs an empty in-memory "HoH" and "HoA" key-store database
163       structure.
164
165        # non-shared or local construction for use by a single process
166
167        use MCE::Shared::Minidb;
168
169        $db = MCE::Shared::Minidb->new();
170
171        # construction for sharing with other threads and processes
172
173        use MCE::Shared;
174
175        $db = MCE::Shared->minidb();
176
177   dump ( "file.dat" )
178       Dumps the in-memory content to a file.
179
180        $db->dump( "content.dat" );
181
182   pipeline ( [ func1, @args ], [ func2, @args ], ... )
183       Combines multiple commands for the object to be processed serially. For
184       shared objects, the call is made atomically due to single IPC to the
185       shared-manager process. The "pipeline" method is fully
186       "wantarray"-aware and receives a list of commands and their arguments.
187       In scalar or list context, it returns data from the last command in the
188       pipeline.
189
190        @vals = $db->pipeline(                     # ( "bar", "baz" )
191           [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
192           [ "hget", "some_key", "f1", "f2" ]
193        );
194
195        $len = $db->pipeline(                      # 2, same as $db->hlen("key2)
196           [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
197           [ "hlen", "some_key" ]
198        );
199
200        $db->pipeline(
201           [ "lset", "key1", 0, "foo" ],
202           [ "hset", "key1", "field1", "foo" ],
203           [ "lset", "key2", 0, "bar", 1, "baz" ],
204           [ "hset", "key2", "field1", "bar", "field2", "baz" ]
205        );
206
207       Current API available since 1.809.
208
209   pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
210       Same as "pipeline", but returns data for every command in the 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", and
251       "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 for
289       the query string, between ":WHERE" and ":ORDER BY", is the same as
290       described above.
291
292       The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC", and
293       "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 and
329       returns its new value. Multiple field_value pairs may be set at once.
330       In that case, the number of fields is returned. This is equivalent to
331       "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 at
341       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 with
348       the field if a single field is given. Otherwise, it returns the number
349       of fields actually removed from the hash stored at key. A field which
350       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 value
363       is returned only if all given fields exist in the hash stored at key.
364
365        if ( $db->hexists( "some_key", "some_field" ) ) { ... }
366        if ( $db->hexists( "some_key", "f1", "f5" ) ) { ... }
367
368   hexists ( key )
369       Determines if a key exists in the first level hash (H)oH.
370
371        if ( $db->hexists( "some_key" ) ) { ... }
372
373   hget ( key, field [, field, ... ] )
374       Gets the values of all given hash fields. The "undef" value is returned
375       for fields which do not exists in the hash stored at key. Likewise, the
376       "undef" value is returned if the key does not exists in the first level
377       hash (H)oH.
378
379        $val = $db->hget( "some_key", "field" );
380
381        ( $val1, $val2 ) = $db->hget( "some_key", "field1", "field2" );
382
383   hget ( key )
384       Gets the "MCE::Shared::Hash" object for the hash stored at key or
385       "undef" if the key does not exists in the first level hash (H)oH.
386
387        $ha_obj = $db->hget( "some_key" );
388
389   hkeys ( key, [ field [, field, ... ] ] )
390       Returns keys stored in the first level hash (H)oH when no arguments are
391       given.  Otherwise, returns the given fields in the hash stored at key.
392       Fields that do not exist will have the "undef" value. In scalar
393       context, returns the size of the object, either the hash stored at key
394       or the first level hash.
395
396        @keys   = $db->hkeys;
397        @fields = $db->hkeys( "some_key" );
398        @fields = $db->hkeys( "some_key", "field1", "field2" );
399        $len    = $db->hkeys( "some_key" );
400        $len    = $db->hkeys;
401
402   hkeys ( key, "query string" )
403       Returns only fields stored at key that match the given criteria. It
404       returns an empty list if the search found nothing. The syntax for the
405       "query string" is described above. In scalar context, returns the size
406       of the resulting list.
407
408        @keys = $db->hkeys( "some_key", "val eq some_value" );
409        @keys = $db->hkeys( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
410        @keys = $db->hkeys( "some_key", "val eq sun :OR val eq moon );
411        $len  = $db->hkeys( "some_key", "key =~ /$pattern/" );
412
413   hkeys ( "query string" )
414       For the one argument form, the search is applied to keys stored in the
415       primary hash only (H)oH. Therefore, the "key" modifier is the only
416       thing possible if wanting any result.
417
418        @keys = $db->hkeys( "key =~ /$pattern/" );
419        $len  = $db->hkeys( "key =~ /$pattern/" );
420
421   hlen ( key [, field ] )
422       Returns the size of the first level hash (H)oH when no arguments are
423       given.  For the given key, returns the size of hash stored at key or
424       optionally, the length of the value stored at key-field. It returns the
425       "undef" value if either the given key or given field does not exists.
426
427        $len = $db->hlen;
428        $len = $db->hlen( $key );
429        $len = $db->hlen( $key, $field );
430
431   hpairs ( key, [ field [, field, ... ] ] )
432       Returns key-value pairs stored in the first level hash (H)oH when no
433       arguments are given. Otherwise, returns field-value pairs for the given
434       fields in the hash stored at key. Fields that do not exist will have
435       the "undef" value. In scalar context, returns the size of the object,
436       either the hash stored at key or the first level hash.
437
438        @pairs = $db->hpairs;                 # ( key => href, ... )
439        @pairs = $db->hpairs( "some_key" );   # ( field => value, ... )
440        @pairs = $db->hpairs( "some_key", "field1", "field2" );
441        $len   = $db->hpairs( "some_key" );
442        $len   = $db->hpairs;
443
444   hpairs ( key, "query string" )
445       Returns only field-value pairs stored at key that match the given
446       criteria.  It returns an empty list if the search found nothing. The
447       syntax for the "query string" is described above. In scalar context,
448       returns the size of the resulting list.
449
450        @pairs = $db->hpairs( "some_key", "val eq some_value" );
451        @pairs = $db->hpairs( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
452        @pairs = $db->hpairs( "some_key", "val eq sun :OR val eq moon" );
453        $len   = $db->hpairs( "some_key", "key =~ /$pattern/" );
454
455   hpairs ( "query string" )
456       For the one argument form, the search is applied to keys stored in the
457       primary hash only (H)oH. Therefore, the "key" modifier is the only
458       thing possible if wanting any result.
459
460        @keys = $db->hpairs( "key =~ /$pattern/" );
461        $len  = $db->hpairs( "key =~ /$pattern/" );
462
463   hset ( key, field, value [, field, value, ... ] )
464       Sets the value of a hash field and returns its new value. Multiple
465       field_value pairs may be set at once. In that case, the number of
466       fields stored at key is returned.
467
468        $val = $db->hset( "some_key", "field", "value" );
469        $len = $db->hset( "some_key", "f1" => "val1", "f2" => "val2" );
470
471   hshift
472       Removes and returns the first key-value pair or value in scalar context
473       from the first-level hash (H)oH. If the "HASH" is empty, returns the
474       undefined value.
475
476        ( $key, $href ) = $db->hshift;
477
478        $href = $db->hshift;
479
480   hsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
481   hsort ( "BY field [ ASC | DESC ] [ ALPHA ]" )
482       Returns sorted keys from the first level hash (H)oH, leaving the
483       elements intact. In void context, sorts the first level hash in-place.
484       Sorting is numeric by default.
485
486        @keys = $db->hsort( "BY key" );
487        @keys = $db->hsort( "BY some_field" );
488
489        $db->hsort( "BY key" );
490        $db->hsort( "BY some_field" );
491
492       If the keys or field values contain string values and you want to sort
493       them lexicographically, specify the "ALPHA" modifier.
494
495        @keys = $db->hsort( "BY key ALPHA" );
496        @keys = $db->hsort( "BY some_field ALPHA" );
497
498        $db->hsort( "BY key ALPHA" );
499        $db->hsort( "BY some_field ALPHA" );
500
501       The default is "ASC" for sorting the elements from small to large. In
502       order to sort from large to small, specify the "DESC" modifier.
503
504        @keys = $db->hsort( "BY key DESC ALPHA" );
505        @keys = $db->hsort( "BY some_field DESC ALPHA" );
506
507        $db->hsort( "BY key DESC ALPHA" );
508        $db->hsort( "BY some_field DESC ALPHA" );
509
510   hvals ( key, [ field [, field, ... ] ] )
511       Returns values stored in the first level hash (H)oH when no arguments
512       are given.  Otherwise, returns values for the given fields in the hash
513       stored at key. Fields that do not exist will have the "undef" value. In
514       scalar context, returns the size of the object, either the hash stored
515       at key or the first level hash.
516
517        @hrefs = $db->hvals;
518        @vals  = $db->hvals( "some_key" );
519        @vals  = $db->hvals( "some_key", "field1", "field2" );
520        $len   = $db->hvals( "some_key" );
521        $len   = $db->hvals;
522
523   hvals ( key, "query string" )
524       Returns only values stored at key that match the given criteria. It
525       returns an empty list if the search found nothing. The syntax for the
526       "query string" is described above. In scalar context, returns the size
527       of the resulting list.
528
529        @vals = $db->hvals( "some_key", "val eq some_value" );
530        @vals = $db->hvals( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
531        @vals = $db->hvals( "some_key", "val eq sun :OR val eq moon" );
532        $len  = $db->hvals( "some_key", "key =~ /$pattern/" );
533
534   hvals ( "query string" )
535       For the one argument form, the search is applied to keys stored in the
536       primary hash only (H)oH. Therefore, the "key" modifier is the only
537       thing possible if wanting any result.
538
539        @keys = $db->hvals( "key =~ /$pattern/" );
540        $len  = $db->hvals( "key =~ /$pattern/" );
541

SUGAR METHODS - HASHES ( HoH )

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

API DOCUMENTATION - LISTS ( HoA )

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

SUGAR METHODS - LISTS ( HoA )

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

CREDITS

917       The implementation is inspired by various Redis Hash/List primitives at
918       <http://redis.io/commands>.
919

INDEX

921       MCE, MCE::Hobo, MCE::Shared
922

AUTHOR

924       Mario E. Roy, <marioeroy AT gmail DOT com>
925
926
927
928perl v5.30.0                      2019-09-19            MCE::Shared::Minidb(3)
Impressum