1MCE::Shared::Minidb(3)User Contributed Perl DocumentationMCE::Shared::Minidb(3)
2
6 MCE::Shared::Minidb - A pure-Perl in-memory data store
7
9 This document describes MCE::Shared::Minidb version 1.840
10
12 A tiny in-memory NoSQL-like database for use as a standalone or managed
13 by MCE::Shared.
14 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 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 # each Ho(H) key => MCE::Shared::Hash->new()
30 # each Ho(A) key => MCE::Shared::Array->new()
31 Several methods described below may resemble the "Redis" API. It is not
33 the intent for this module to become 100% compatible.
34
36 # non-shared or local construction for use by a single process
37 use MCE::Shared::Minidb;
39 my $db = MCE::Shared::Minidb->new();
41 # construction for sharing with other threads and processes
43 use MCE::Shared;
45 my $db = MCE::Shared->minidb();
47 # Hash of Hashes (HoH)
49 # Update the hash stored at key1/key2
50 $db->hset( "key1", "f1", "foo" );
52 $db->hset( "key2", "f1", "bar", "f2", "baz" );
53 $val = $db->hget( "key2", "f2" ); # "baz"
55 # Hash of Lists (HoA)
57 # Update the list stored at key1/key2
58 $db->lset( "key1", 0, "foo" );
60 $db->lset( "key2", 0, "bar", 1, "baz" );
61 $val = $db->lget( "key2", 1 ); # "baz"
63 # pipeline, provides atomicity for shared objects, MCE::Shared v1.09+
65 $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
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 o Basic demonstration
81 # 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 # query the top-level hash (H)oH
87 @keys = $db->hkeys( "query string given here" );
88 @keys = $db->hkeys( "key =~ /pattern/" );
89 o Supported operators: =~ !~ eq ne lt le gt ge == != < <= > >=
91 o Multiple expressions delimited by :AND or :OR, mixed case allowed
92 "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 * 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 o Quoting is optional inside the string
104 o Primary keys (H)oH may have spaces, but not so for field_names
105 "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 "key =~ 'some key' :AND 'some_field' eq 'foo bar'" # ok: some_field
110 "key =~ some key :AND some_field eq foo bar"
111 "key =~ 'some key' :AND 'some field' eq 'foo bar'" # fail: some field
113 "key =~ some key :AND some field eq foo bar"
114 Examples.
116 # search capability key/val: =~ !~ eq ne lt le gt ge == != < <= > >=
118 # key/val means to match against actual key/val respectively
119 # a query made to a hash stored at "some key"
121 # note that "fieldNames" must not have spaces
122 @keys = $db->hkeys(
124 "some key", "key eq some_field :or (val > 5 :and val < 9)"
125 );
126 # queries made to a list stored at "some key"
128 @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 # 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 @keys = $db->hkeys( "key eq 'some key'" );
136 @keys = $db->hkeys( "key eq some key" );
137 @keys = $db->hkeys( "key =~ /$pattern/i" );
139 @keys = $db->hkeys( "key !~ /$pattern/i" );
140 %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 @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 # see select_aref and select_href below for db-like queries against
157 # the underlying Ho(A) and Ho(H) structures respectively
158
160 new
161 Constructs an empty in-memory "HoH" and "HoA" key-store database
162 structure.
163 # non-shared or local construction for use by a single process
165 use MCE::Shared::Minidb;
167 $db = MCE::Shared::Minidb->new();
169 # construction for sharing with other threads and processes
171 use MCE::Shared;
173 $db = MCE::Shared->minidb();
175 dump ( "file.dat" )
177 Dumps the in-memory content to a file.
178 $db->dump( "content.dat" );
180 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 @vals = $db->pipeline( # ( "bar", "baz" )
190 [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
191 [ "hget", "some_key", "f1", "f2" ]
192 );
193 $len = $db->pipeline( # 2, same as $db->hlen("key2)
195 [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
196 [ "hlen", "some_key" ]
197 );
198 $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 Current API available since 1.809.
207 pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
209 Same as "pipeline", but returns data for every command in the
210 pipeline.
211 @vals = $db->pipeline_ex( # ( "bar", "baz" )
213 [ "hset", "key3", "field1", "bar" ],
214 [ "hset", "key3", "field2", "baz" ]
215 );
216 $chunk_size = 3;
218 $db->hset("some_key", chunk_id => 0);
220 $db->lassign("some_key", @ARGV);
221 while (1) {
223 ($chunk_id, @next) = $db->pipeline_ex(
224 [ "hincr", "some_key", "chunk_id" ],
225 [ "lsplice", "some_key", 0, $chunk_size ]
226 );
227 last unless @next;
229 ...
231 }
232 Current API available since 1.809.
234 restore ( "file.dat" )
236 Restores the in-memory content from a file.
237 $db->restore( "content.dat" );
239 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 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 The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC",
251 and "ALPHA" may be mixed case. e.g. ":Where"
252 HoH select string:
254 "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 * key matches on keys stored in the primary level hash (H)oH
261 HoH select synopsis:
263 @rows = $db->select_aref( ":hashes", "some_field :ORDER BY some_field" );
265 @rows = $db->select_aref( ":hashes", "f2 f6 f5 :ORDER BY f4" );
266 # $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 @rows = $db->select_href( ":hashes", "some_field :ORDER BY some_field" );
274 @rows = $db->select_href( ":hashes", "f2 f6 f5 :ORDER BY f4" );
275 # $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 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 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 The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC",
293 and "ALPHA" may be mixed case. e.g. ":Where"
294 HoA select string:
296 "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 * 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 HoA select synopsis:
307 @rows = $db->select_aref( ":lists", "some_index :ORDER BY some_index" );
309 @rows = $db->select_aref( ":lists", "2 6 5 :ORDER BY 4" );
310 # $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 @rows = $db->select_href( ":lists", "some_index :ORDER BY some_index" );
318 @rows = $db->select_href( ":lists", "2 6 5 :ORDER BY 4" );
319 # $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
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 $val = $db->hassign( "some_key", "field", "value" );
334 $len = $db->hassign( "some_key", "f1" => "val1", "f2" => "val2" );
335 API available since 1.007.
337 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 $db->hclear;
344 $db->hclear( "some_key" );
345 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 $val = $db->hdel( "some_key", "some_field" );
353 $cnt = $db->hdel( "some_key", "field1", "field2" );
354 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 $ha_obj = $db->hdel( "some_key" );
360 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 if ( $db->hexists( "some_key", "some_field" ) ) { ... }
367 if ( $db->hexists( "some_key", "f1", "f5" ) ) { ... }
368 hexists ( key )
370 Determines if a key exists in the first level hash (H)oH.
371 if ( $db->hexists( "some_key" ) ) { ... }
373 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 $val = $db->hget( "some_key", "field" );
381 ( $val1, $val2 ) = $db->hget( "some_key", "field1", "field2" );
383 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 $ha_obj = $db->hget( "some_key" );
389 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 @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 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 @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 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 @keys = $db->hkeys( "key =~ /$pattern/" );
420 $len = $db->hkeys( "key =~ /$pattern/" );
421 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 $len = $db->hlen;
430 $len = $db->hlen( $key );
431 $len = $db->hlen( $key, $field );
432 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 @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 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 @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 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 @keys = $db->hpairs( "key =~ /$pattern/" );
463 $len = $db->hpairs( "key =~ /$pattern/" );
464 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 $val = $db->hset( "some_key", "field", "value" );
471 $len = $db->hset( "some_key", "f1" => "val1", "f2" => "val2" );
472 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 ( $key, $href ) = $db->hshift;
479 $href = $db->hshift;
481 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 @keys = $db->hsort( "BY key" );
489 @keys = $db->hsort( "BY some_field" );
490 $db->hsort( "BY key" );
492 $db->hsort( "BY some_field" );
493 If the keys or field values contain string values and you want to
495 sort them lexicographically, specify the "ALPHA" modifier.
496 @keys = $db->hsort( "BY key ALPHA" );
498 @keys = $db->hsort( "BY some_field ALPHA" );
499 $db->hsort( "BY key ALPHA" );
501 $db->hsort( "BY some_field ALPHA" );
502 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 @keys = $db->hsort( "BY key DESC ALPHA" );
507 @keys = $db->hsort( "BY some_field DESC ALPHA" );
508 $db->hsort( "BY key DESC ALPHA" );
510 $db->hsort( "BY some_field DESC ALPHA" );
511 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 @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 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 @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 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 @keys = $db->hvals( "key =~ /$pattern/" );
542 $len = $db->hvals( "key =~ /$pattern/" );
543
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 happend ( key, field, string )
550 Appends a value to key-field and returns its new length.
551 $len = $db->happend( $key, $field, "foo" );
553 hdecr ( key, field )
555 Decrements the value of key-field by one and returns its new value.
556 $num = $db->hdecr( $key, $field );
558 hdecrby ( key, field, number )
560 Decrements the value of key-field by the given number and returns
561 its new value.
562 $num = $db->hdecrby( $key, $field, 2 );
564 hgetdecr ( key, field )
566 Decrements the value of key-field by one and returns its old value.
567 $old = $db->hgetdecr( $key, $field );
569 hgetincr ( key, field )
571 Increments the value of key-field by one and returns its old value.
572 $old = $db->hgetincr( $key, $field );
574 hgetset ( key, field, value )
576 Sets the value of key-field and returns its old value.
577 $old = $db->hgetset( $key, $field, "baz" );
579 hincr ( key, field )
581 Increments the value of key-field by one and returns its new value.
582 $num = $db->hincr( $key, $field );
584 hincrby ( key, field, number )
586 Increments the value of key-field by the given number and returns
587 its new value.
588 $num = $db->hincrby( $key, $field, 2 );
590
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 $len = $db->lassign( "some_key", "val1", "val2" );
597 API available since 1.007.
599 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 $db->lclear;
606 $db->lclear( "some_key" );
607 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 $val = $db->ldel( "some_key", 20 );
615 $cnt = $db->ldel( "some_key", 0, 1 );
616 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 $ar_obj = $db->ldel( "some_key" );
622 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 $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 $db->lexists( "some_key", 2 ); # True
635 $db->lexists( "some_key", 2, 3 ); # True
636 $db->ldel ( "some_key", 2 ); # value2
637 $db->lexists( "some_key", 2 ); # False
639 $db->lexists( "some_key", 2, 3 ); # False
640 $db->lexists( "some_key", 3 ); # True
641 lexists ( key )
643 Determines if a key exists in the first level hash (H)oA.
644 if ( $db->lexists( "some_key" ) ) { ... }
646 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 $val = $db->lget( "some_key", 20 );
654 ( $val1, $val2 ) = $db->lget( "some_key", 0, 1 );
656 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 $ar_obj = $db->lget( "some_key" );
662 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 @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 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 @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 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 @keys = $db->lkeys( "key =~ /$pattern/" );
693 $len = $db->lkeys( "key =~ /$pattern/" );
694 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 $len = $db->llen;
703 $len = $db->llen( $key );
704 $len = $db->llen( $key, 0 );
705 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 @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 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 @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 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 @keys = $db->lpairs( "key =~ /$pattern/" );
736 $len = $db->lpairs( "key =~ /$pattern/" );
737 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 $val = $db->lpop( $key );
743 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 $len = $db->lpush( "some_key", "val1", "val2" );
749 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 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 @list = $db->lrange( "some_key", 20, 29 );
760 @list = $db->lrange( "some_key", -4, -1 );
761 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 $val = $db->lset( "some_key", 2, "value" );
768 $len = $db->lset( "some_key", 0 => "val1", 1 => "val2" );
769 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 ( $key, $aref ) = $db->lshift;
777 $aref = $db->lshift;
779 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 @keys = $db->lsort( "BY key" );
787 @keys = $db->lsort( "BY some_index" );
788 $db->lsort( "BY key" );
790 $db->lsort( "BY some_index" );
791 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 @keys = $db->lsort( "BY key ALPHA" );
797 @keys = $db->lsort( "BY some_index ALPHA" );
798 $db->lsort( "BY key ALPHA" );
800 $db->lsort( "BY some_index ALPHA" );
801 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 @keys = $db->lsort( "BY key DESC ALPHA" );
806 @keys = $db->lsort( "BY some_index DESC ALPHA" );
807 $db->lsort( "BY key DESC ALPHA" );
809 $db->lsort( "BY some_index DESC ALPHA" );
810 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 $db->lsort( "some_key", "BY key DESC" );
819 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 @items = $db->lsplice( "some_key", 20, 2, @list );
826 @items = $db->lsplice( "some_key", 20, 2 );
827 @items = $db->lsplice( "some_key", 20 );
828 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 @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 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 @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 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 @keys = $db->lvals( "key =~ /$pattern/" );
859 $len = $db->lvals( "key =~ /$pattern/" );
860 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 $val = $db->rpop( $key );
866 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 $len = $db->rpush( "some_key", "val1", "val2" );
872
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 lappend ( key, index, string )
879 Appends a value to key-index and returns its new length.
880 $len = $db->lappend( $key, 0, "foo" );
882 ldecr ( key, index )
884 Decrements the value of key-index by one and returns its new value.
885 $num = $db->ldecr( $key, 0 );
887 ldecrby ( key, index, number )
889 Decrements the value of key-index by the given number and returns
890 its new value.
891 $num = $db->ldecrby( $key, 0, 2 );
893 lgetdecr ( key, index )
895 Decrements the value of key-index by one and returns its old value.
896 $old = $db->lgetdecr( $key, 0 );
898 lgetincr ( key, index )
900 Increments the value of key-index by one and returns its old value.
901 $old = $db->lgetincr( $key, 0 );
903 lgetset ( key, index, value )
905 Sets the value of key-index and return its old value.
906 $old = $db->lgetset( $key, 0, "baz" );
908 lincr ( key, index )
910 Increments the value of key-index by one and returns its new value.
911 $num = $db->lincr( $key, 0 );
913 lincrby ( key, index, number )
915 Increments the value of key-index by the given number and returns
916 its new value.
917 $num = $db->lincrby( $key, 0, 2 );
919
921 The implementation is inspired by various Redis Hash/List primitives at
922 <http://redis.io/commands>.
923
925 MCE, MCE::Hobo, MCE::Shared
926
928 Mario E. Roy, <marioeroy AT gmail DOT com>
929perl v5.28.1 2019-01-04 MCE::Shared::Minidb(3)