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.877
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 MCE::Shared::Minidb->new ()
161 MCE::Shared->minidb ()
162 Constructs an empty in-memory "HoH" and "HoA" key-store database
163 structure.
164 # non-shared or local construction for use by a single process
166 use MCE::Shared::Minidb;
168 $db = MCE::Shared::Minidb->new();
170 # construction for sharing with other threads and processes
172 use MCE::Shared;
174 $db = MCE::Shared->minidb();
176 dump ( "file.dat" )
178 Dumps the in-memory content to a file.
179 $db->dump( "content.dat" );
181 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 @vals = $db->pipeline( # ( "bar", "baz" )
191 [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
192 [ "hget", "some_key", "f1", "f2" ]
193 );
194 $len = $db->pipeline( # 2, same as $db->hlen("key2)
196 [ "hset", "some_key", "f1", "bar", "f2", "baz" ],
197 [ "hlen", "some_key" ]
198 );
199 $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 Current API available since 1.809.
208 pipeline_ex ( [ func1, @args ], [ func2, @args ], ... )
210 Same as "pipeline", but returns data for every command in the 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", and
251 "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 for
289 the query string, between ":WHERE" and ":ORDER BY", is the same as
290 described above.
291 The modifiers ":WHERE", ":AND", ":OR", "ORDER BY", "ASC", "DESC", and
293 "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 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 $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 at
341 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 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 $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 value
363 is returned only if all given fields exist in the hash stored at key.
364 if ( $db->hexists( "some_key", "some_field" ) ) { ... }
366 if ( $db->hexists( "some_key", "f1", "f5" ) ) { ... }
367 hexists ( key )
369 Determines if a key exists in the first level hash (H)oH.
370 if ( $db->hexists( "some_key" ) ) { ... }
372 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 $val = $db->hget( "some_key", "field" );
380 ( $val1, $val2 ) = $db->hget( "some_key", "field1", "field2" );
382 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 $ha_obj = $db->hget( "some_key" );
388 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 @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 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 @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 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 @keys = $db->hkeys( "key =~ /$pattern/" );
419 $len = $db->hkeys( "key =~ /$pattern/" );
420 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 $len = $db->hlen;
428 $len = $db->hlen( $key );
429 $len = $db->hlen( $key, $field );
430 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 @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 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 @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 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 @keys = $db->hpairs( "key =~ /$pattern/" );
461 $len = $db->hpairs( "key =~ /$pattern/" );
462 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 $val = $db->hset( "some_key", "field", "value" );
469 $len = $db->hset( "some_key", "f1" => "val1", "f2" => "val2" );
470 hsetnx ( key, field, value )
472 Sets the value of a hash field, only if the field does not exist.
473 Returns a 1 for new field or 0 if the field already exists and no
474 operation was performed.
475 $ret = $db->hsetnx( "some_key", "field", "value" );
477 Current API available since 1.872.
479 hshift
481 Removes and returns the first key-value pair or value in scalar context
482 from the first-level hash (H)oH. If the "HASH" is empty, returns the
483 undefined value.
484 ( $key, $href ) = $db->hshift;
486 $href = $db->hshift;
488 hsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
490 hsort ( "BY field [ ASC | DESC ] [ ALPHA ]" )
491 Returns sorted keys from the first level hash (H)oH, leaving the
492 elements intact. In void context, sorts the first level hash in-place.
493 Sorting is numeric by default.
494 @keys = $db->hsort( "BY key" );
496 @keys = $db->hsort( "BY some_field" );
497 $db->hsort( "BY key" );
499 $db->hsort( "BY some_field" );
500 If the keys or field values contain string values and you want to sort
502 them lexicographically, specify the "ALPHA" modifier.
503 @keys = $db->hsort( "BY key ALPHA" );
505 @keys = $db->hsort( "BY some_field ALPHA" );
506 $db->hsort( "BY key ALPHA" );
508 $db->hsort( "BY some_field ALPHA" );
509 The default is "ASC" for sorting the elements from small to large. In
511 order to sort from large to small, specify the "DESC" modifier.
512 @keys = $db->hsort( "BY key DESC ALPHA" );
514 @keys = $db->hsort( "BY some_field DESC ALPHA" );
515 $db->hsort( "BY key DESC ALPHA" );
517 $db->hsort( "BY some_field DESC ALPHA" );
518 hvals ( key, [ field [, field, ... ] ] )
520 Returns values stored in the first level hash (H)oH when no arguments
521 are given. Otherwise, returns values for the given fields in the hash
522 stored at key. Fields that do not exist will have the "undef" value. In
523 scalar context, returns the size of the object, either the hash stored
524 at key or the first level hash.
525 @hrefs = $db->hvals;
527 @vals = $db->hvals( "some_key" );
528 @vals = $db->hvals( "some_key", "field1", "field2" );
529 $len = $db->hvals( "some_key" );
530 $len = $db->hvals;
531 hvals ( key, "query string" )
533 Returns only values stored at key that match the given criteria. It
534 returns an empty list if the search found nothing. The syntax for the
535 "query string" is described above. In scalar context, returns the size
536 of the resulting list.
537 @vals = $db->hvals( "some_key", "val eq some_value" );
539 @vals = $db->hvals( "some_key", "key eq some_key :AND val =~ /sun|moon/" );
540 @vals = $db->hvals( "some_key", "val eq sun :OR val eq moon" );
541 $len = $db->hvals( "some_key", "key =~ /$pattern/" );
542 hvals ( "query string" )
544 For the one argument form, the search is applied to keys stored in the
545 primary hash only (H)oH. Therefore, the "key" modifier is the only
546 thing possible if wanting any result.
547 @keys = $db->hvals( "key =~ /$pattern/" );
549 $len = $db->hvals( "key =~ /$pattern/" );
550
552 This module is equipped with sugar methods to not have to call "set"
553 and "get" explicitly. In shared context, the benefit is atomicity and
554 reduction in inter-process communication.
555 happend ( key, field, string )
557 Appends a value to key-field and returns its new length.
558 $len = $db->happend( $key, $field, "foo" );
560 hdecr ( key, field )
562 Decrements the value of key-field by one and returns its new value.
563 $num = $db->hdecr( $key, $field );
565 hdecrby ( key, field, number )
567 Decrements the value of key-field by the given number and returns its
568 new value.
569 $num = $db->hdecrby( $key, $field, 2 );
571 hgetdecr ( key, field )
573 Decrements the value of key-field by one and returns its old value.
574 $old = $db->hgetdecr( $key, $field );
576 hgetincr ( key, field )
578 Increments the value of key-field by one and returns its old value.
579 $old = $db->hgetincr( $key, $field );
581 hgetset ( key, field, value )
583 Sets the value of key-field and returns its old value.
584 $old = $db->hgetset( $key, $field, "baz" );
586 hincr ( key, field )
588 Increments the value of key-field by one and returns its new value.
589 $num = $db->hincr( $key, $field );
591 hincrby ( key, field, number )
593 Increments the value of key-field by the given number and returns its
594 new value.
595 $num = $db->hincrby( $key, $field, 2 );
597
599 lassign ( key, value [, value, ... ] )
600 Clears the list stored at key, then prepends one or multiple values and
601 returns the new length. This is equivalent to "lclear", "lpush".
602 $len = $db->lassign( "some_key", "val1", "val2" );
604 API available since 1.007.
606 lclear ( key )
608 Removes all key-value pairs from the first level hash (H)oA when no
609 arguments are given. Otherwise, removes all elements from the list
610 stored at key.
611 $db->lclear;
613 $db->lclear( "some_key" );
614 ldel ( key, index [, index, ... ] )
616 Deletes one or more elements by their indices. It returns the value
617 associated with the index if a single index is given. Otherwise, it
618 returns the number of elements actually removed from the list stored at
619 key. An index which does not exists in the list is not counted.
620 $val = $db->ldel( "some_key", 20 );
622 $cnt = $db->ldel( "some_key", 0, 1 );
623 ldel ( key )
625 Deletes and returns the "MCE::Shared::Array" object stored at key or
626 "undef" if the key does not exists in the first level hash (H)oA.
627 $ar_obj = $db->ldel( "some_key" );
629 lexists ( key, index [, index, ... ] )
631 Determines if elements by their indices exist in the list. For multiple
632 indices, a truth value is returned only if all given indices exist in
633 the list stored at key. The behavior is strongly tied to the use of
634 delete on lists.
635 $db->lset( "some_key", 0, "value0" );
637 $db->lset( "some_key", 1, "value1" );
638 $db->lset( "some_key", 2, "value2" );
639 $db->lset( "some_key", 3, "value3" );
640 $db->lexists( "some_key", 2 ); # True
642 $db->lexists( "some_key", 2, 3 ); # True
643 $db->ldel ( "some_key", 2 ); # value2
644 $db->lexists( "some_key", 2 ); # False
646 $db->lexists( "some_key", 2, 3 ); # False
647 $db->lexists( "some_key", 3 ); # True
648 lexists ( key )
650 Determines if a key exists in the first level hash (H)oA.
651 if ( $db->lexists( "some_key" ) ) { ... }
653 lget ( key, index [, index, ... ] )
655 Gets the values of all given list indices. The "undef" value is
656 returned for indices which do not exists in the list stored at key.
657 Likewise, the "undef" value is returned if the key does not exists in
658 the first level hash (H)oA.
659 $val = $db->lget( "some_key", 20 );
661 ( $val1, $val2 ) = $db->lget( "some_key", 0, 1 );
663 lget ( key )
665 Gets the "MCE::Shared::Array" object for the list stored at key or
666 "undef" if the key does not exists in the first level hash (H)oA.
667 $ar_obj = $db->lget( "some_key" );
669 lkeys ( key, [ index [, index, ... ] ] )
671 Returns keys stored in the first level hash (H)oA when no arguments are
672 given. Otherwise, returns the given indices in the list stored at key.
673 Indices that do not exist will have the "undef" value. In scalar
674 context, returns the size of the object, either the list stored at key
675 or the first level hash.
676 @keys = $db->lkeys;
678 @indices = $db->lkeys( "some_key" );
679 @indices = $db->lkeys( "some_key", 0, 1 );
680 $len = $db->lkeys( "some_key" );
681 $len = $db->lkeys;
682 lkeys ( key, "query string" )
684 Returns only indices stored at key that match the given criteria. It
685 returns an empty list if the search found nothing. The syntax for the
686 "query string" is described above. In scalar context, returns the size
687 of the resulting list.
688 @keys = $db->lkeys( "some_key", "val eq some_value" );
690 @keys = $db->lkeys( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
691 @keys = $db->lkeys( "some_key", "val eq sun :OR val eq moon" );
692 $len = $db->lkeys( "some_key", "key =~ /$pattern/" );
693 lkeys ( "query string" )
695 For the one argument form, the search is applied to keys stored in the
696 primary hash only (H)oA. Therefore, the "key" modifier is the only
697 thing possible if wanting any result.
698 @keys = $db->lkeys( "key =~ /$pattern/" );
700 $len = $db->lkeys( "key =~ /$pattern/" );
701 llen ( key [, index ] )
703 Returns the size of the first level hash (H)oA when no arguments are
704 given. For the given index, returns the size of list stored at key or
705 optionally, the length of the value stored at key-index. It returns the
706 "undef" value if either the given key or given index does not exists.
707 $len = $db->llen;
709 $len = $db->llen( $key );
710 $len = $db->llen( $key, 0 );
711 lpairs ( key, [ index [, index, ... ] ] )
713 Returns key-value pairs stored in the first level hash (H)oA when no
714 arguments are given. Otherwise, returns index-value pairs for the given
715 indices in the list stored at key. Indices that do not exist will have
716 the "undef" value. In scalar context, returns the size of the object,
717 either the list stored at key or the first level hash.
718 @pairs = $db->lpairs; # ( key => aref, ... )
720 @pairs = $db->lpairs( "some_key" ); # ( index => value, ... )
721 @pairs = $db->lpairs( "some_key", 0, 1 );
722 $len = $db->lpairs( "some_key" );
723 $len = $db->lpairs;
724 lpairs ( key, "query string" )
726 Returns only index-value pairs stored at key that match the given
727 criteria. It returns an empty list if the search found nothing. The
728 syntax for the "query string" is described above. In scalar context,
729 returns the size of the resulting list.
730 @pairs = $db->lpairs( "some_key", "val eq some_value" );
732 @pairs = $db->lpairs( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
733 @pairs = $db->lpairs( "some_key", "val eq sun :OR val eq moon" );
734 $len = $db->lpairs( "some_key", "key =~ /$pattern/" );
735 lpairs ( "query string" )
737 For the one argument form, the search is applied to keys stored in the
738 primary hash only (H)oA. Therefore, the "key" modifier is the only
739 thing possible if wanting any result.
740 @keys = $db->lpairs( "key =~ /$pattern/" );
742 $len = $db->lpairs( "key =~ /$pattern/" );
743 lpop ( key )
745 Removes and returns the first value of the list stored at key. If there
746 are no elements in the list, returns the undefined value.
747 $val = $db->lpop( $key );
749 lpush ( key, value [, value, ... ] )
751 Prepends one or multiple values to the head of the list stored at key
752 and returns the new length.
753 $len = $db->lpush( "some_key", "val1", "val2" );
755 lrange ( key, start, stop )
757 Returns the specified elements of the list stored at key. The offsets
758 "start" and "stop" can also be negative numbers indicating offsets
759 starting at the end of the list.
760 An empty list is returned if "start" is larger than the end of the
762 list. "stop" is set to the last index of the list if larger than the
763 actual end of the list.
764 @list = $db->lrange( "some_key", 20, 29 );
766 @list = $db->lrange( "some_key", -4, -1 );
767 lset ( key, index, value [, index, value, ... ] )
769 Sets the value of an element in a list by its index and returns its new
770 value. Multiple index_value pairs may be set all at once. In that
771 case, the length of the list is returned.
772 $val = $db->lset( "some_key", 2, "value" );
774 $len = $db->lset( "some_key", 0 => "val1", 1 => "val2" );
775 lshift
777 Removes and returns the first key-value pair or value in scalar context
778 from the first-level hash (H)oA. If the "HASH" is empty, returns the
779 undefined value. See "lpop" to shift the first value of the list stored
780 at key.
781 ( $key, $aref ) = $db->lshift;
783 $aref = $db->lshift;
785 lsort ( "BY key [ ASC | DESC ] [ ALPHA ]" )
787 lsort ( "BY index [ ASC | DESC ] [ ALPHA ]" )
788 Returns sorted keys from the first level hash (H)oA, leaving the
789 elements intact. In void context, sorts the first level hash in-place.
790 Sorting is numeric by default.
791 @keys = $db->lsort( "BY key" );
793 @keys = $db->lsort( "BY some_index" );
794 $db->lsort( "BY key" );
796 $db->lsort( "BY some_index" );
797 If the keys or field values given by index contain string values and
799 you want to sort them lexicographically, specify the "ALPHA" modifier.
800 @keys = $db->lsort( "BY key ALPHA" );
802 @keys = $db->lsort( "BY some_index ALPHA" );
803 $db->lsort( "BY key ALPHA" );
805 $db->lsort( "BY some_index ALPHA" );
806 The default is "ASC" for sorting the elements from small to large. In
808 order to sort from large to small, specify the "DESC" modifier.
809 @keys = $db->lsort( "BY key DESC ALPHA" );
811 @keys = $db->lsort( "BY some_index DESC ALPHA" );
812 $db->lsort( "BY key DESC ALPHA" );
814 $db->lsort( "BY some_index DESC ALPHA" );
815 lsort ( key, "BY key [ ASC | DESC ] [ ALPHA ]" )
817 lsort ( key, "BY val [ ASC | DESC ] [ ALPHA ]" )
818 The two argument form has similar functionality. Here, sorting is
819 applied to the list stored at key. For example, the following reverses
820 the list stored at the given key. The "BY key" modifier refers to the
821 indices in the list and not the values.
822 $db->lsort( "some_key", "BY key DESC" );
824 lsplice ( key, offset [, length [, list ] ] )
826 Removes the elements designated by "offset" and "length" from the array
827 stored at key, and replaces them with the elements of "list", if any.
828 The behavior is similar to the Perl "splice" function.
829 @items = $db->lsplice( "some_key", 20, 2, @list );
831 @items = $db->lsplice( "some_key", 20, 2 );
832 @items = $db->lsplice( "some_key", 20 );
833 lvals ( key, [ index [, index, ... ] ] )
835 Returns values stored in the first level hash (H)oA when no arguments
836 are given. Otherwise, returns values for the given indices in the list
837 stored at key. Indices that do not exist will have the "undef" value.
838 In scalar context, returns the size of the object, either the list
839 stored at key or the first level hash.
840 @arefs = $db->lvals;
842 @vals = $db->lvals( "some_key" );
843 @vals = $db->lvals( "some_key", 0, 1 );
844 $len = $db->lvals( "some_key" );
845 $len = $db->lvals;
846 lvals ( key, "query string" )
848 Returns only values stored at key that match the given criteria. It
849 returns an empty list if the search found nothing. The syntax for the
850 "query string" is described above. In scalar context, returns the size
851 of the resulting list.
852 @keys = $db->lvals( "some_key", "val eq some_value" );
854 @keys = $db->lvals( "some_key", "key >= 50 :AND val =~ /sun|moon/" );
855 @keys = $db->lvals( "some_key", "val eq sun :OR val eq moon" );
856 $len = $db->lvals( "some_key", "key =~ /$pattern/" );
857 lvals ( "query string" )
859 For the one argument form, the search is applied to keys stored in the
860 primary hash only (H)oA. Therefore, the "key" modifier is the only
861 thing possible if wanting any result.
862 @keys = $db->lvals( "key =~ /$pattern/" );
864 $len = $db->lvals( "key =~ /$pattern/" );
865 rpop ( key )
867 Removes and returns the last value of the list stored at key. If there
868 are no elements in the list, returns the undefined value.
869 $val = $db->rpop( $key );
871 rpush ( key, value [, value, ... ] )
873 Appends one or multiple values to the tail of the list stored at key
874 and returns the new length.
875 $len = $db->rpush( "some_key", "val1", "val2" );
877
879 This module is equipped with sugar methods to not have to call "set"
880 and "get" explicitly. In shared context, the benefit is atomicity and
881 reduction in inter-process communication.
882 lappend ( key, index, string )
884 Appends a value to key-index and returns its new length.
885 $len = $db->lappend( $key, 0, "foo" );
887 ldecr ( key, index )
889 Decrements the value of key-index by one and returns its new value.
890 $num = $db->ldecr( $key, 0 );
892 ldecrby ( key, index, number )
894 Decrements the value of key-index by the given number and returns its
895 new value.
896 $num = $db->ldecrby( $key, 0, 2 );
898 lgetdecr ( key, index )
900 Decrements the value of key-index by one and returns its old value.
901 $old = $db->lgetdecr( $key, 0 );
903 lgetincr ( key, index )
905 Increments the value of key-index by one and returns its old value.
906 $old = $db->lgetincr( $key, 0 );
908 lgetset ( key, index, value )
910 Sets the value of key-index and returns its old value.
911 $old = $db->lgetset( $key, 0, "baz" );
913 lincr ( key, index )
915 Increments the value of key-index by one and returns its new value.
916 $num = $db->lincr( $key, 0 );
918 lincrby ( key, index, number )
920 Increments the value of key-index by the given number and returns its
921 new value.
922 $num = $db->lincrby( $key, 0, 2 );
924
926 The implementation is inspired by various Redis Hash/List primitives at
927 <https://redis.io/commands>.
928
930 MCE, MCE::Hobo, MCE::Shared
931
933 Mario E. Roy, <marioeroy AT gmail DOT com>
934perl v5.36.0 2022-07-22 MCE::Shared::Minidb(3)