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.864
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 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 ( $key, $href ) = $db->hshift;
477 $href = $db->hshift;
479 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 @keys = $db->hsort( "BY key" );
487 @keys = $db->hsort( "BY some_field" );
488 $db->hsort( "BY key" );
490 $db->hsort( "BY some_field" );
491 If the keys or field values contain string values and you want to sort
493 them lexicographically, specify the "ALPHA" modifier.
494 @keys = $db->hsort( "BY key ALPHA" );
496 @keys = $db->hsort( "BY some_field ALPHA" );
497 $db->hsort( "BY key ALPHA" );
499 $db->hsort( "BY some_field ALPHA" );
500 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 @keys = $db->hsort( "BY key DESC ALPHA" );
505 @keys = $db->hsort( "BY some_field DESC ALPHA" );
506 $db->hsort( "BY key DESC ALPHA" );
508 $db->hsort( "BY some_field DESC ALPHA" );
509 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 @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 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 @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 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 @keys = $db->hvals( "key =~ /$pattern/" );
540 $len = $db->hvals( "key =~ /$pattern/" );
541
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 happend ( key, field, string )
548 Appends a value to key-field and returns its new length.
549 $len = $db->happend( $key, $field, "foo" );
551 hdecr ( key, field )
553 Decrements the value of key-field by one and returns its new value.
554 $num = $db->hdecr( $key, $field );
556 hdecrby ( key, field, number )
558 Decrements the value of key-field by the given number and returns its
559 new value.
560 $num = $db->hdecrby( $key, $field, 2 );
562 hgetdecr ( key, field )
564 Decrements the value of key-field by one and returns its old value.
565 $old = $db->hgetdecr( $key, $field );
567 hgetincr ( key, field )
569 Increments the value of key-field by one and returns its old value.
570 $old = $db->hgetincr( $key, $field );
572 hgetset ( key, field, value )
574 Sets the value of key-field and returns its old value.
575 $old = $db->hgetset( $key, $field, "baz" );
577 hincr ( key, field )
579 Increments the value of key-field by one and returns its new value.
580 $num = $db->hincr( $key, $field );
582 hincrby ( key, field, number )
584 Increments the value of key-field by the given number and returns its
585 new value.
586 $num = $db->hincrby( $key, $field, 2 );
588
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 $len = $db->lassign( "some_key", "val1", "val2" );
595 API available since 1.007.
597 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 $db->lclear;
604 $db->lclear( "some_key" );
605 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 $val = $db->ldel( "some_key", 20 );
613 $cnt = $db->ldel( "some_key", 0, 1 );
614 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 $ar_obj = $db->ldel( "some_key" );
620 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 $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 $db->lexists( "some_key", 2 ); # True
633 $db->lexists( "some_key", 2, 3 ); # True
634 $db->ldel ( "some_key", 2 ); # value2
635 $db->lexists( "some_key", 2 ); # False
637 $db->lexists( "some_key", 2, 3 ); # False
638 $db->lexists( "some_key", 3 ); # True
639 lexists ( key )
641 Determines if a key exists in the first level hash (H)oA.
642 if ( $db->lexists( "some_key" ) ) { ... }
644 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 $val = $db->lget( "some_key", 20 );
652 ( $val1, $val2 ) = $db->lget( "some_key", 0, 1 );
654 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 $ar_obj = $db->lget( "some_key" );
660 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 @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 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 @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 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 @keys = $db->lkeys( "key =~ /$pattern/" );
691 $len = $db->lkeys( "key =~ /$pattern/" );
692 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 $len = $db->llen;
700 $len = $db->llen( $key );
701 $len = $db->llen( $key, 0 );
702 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 @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 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 @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 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 @keys = $db->lpairs( "key =~ /$pattern/" );
733 $len = $db->lpairs( "key =~ /$pattern/" );
734 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 $val = $db->lpop( $key );
740 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 $len = $db->lpush( "some_key", "val1", "val2" );
746 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 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 @list = $db->lrange( "some_key", 20, 29 );
757 @list = $db->lrange( "some_key", -4, -1 );
758 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 $val = $db->lset( "some_key", 2, "value" );
765 $len = $db->lset( "some_key", 0 => "val1", 1 => "val2" );
766 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 ( $key, $aref ) = $db->lshift;
774 $aref = $db->lshift;
776 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 @keys = $db->lsort( "BY key" );
784 @keys = $db->lsort( "BY some_index" );
785 $db->lsort( "BY key" );
787 $db->lsort( "BY some_index" );
788 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 @keys = $db->lsort( "BY key ALPHA" );
793 @keys = $db->lsort( "BY some_index ALPHA" );
794 $db->lsort( "BY key ALPHA" );
796 $db->lsort( "BY some_index ALPHA" );
797 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 @keys = $db->lsort( "BY key DESC ALPHA" );
802 @keys = $db->lsort( "BY some_index DESC ALPHA" );
803 $db->lsort( "BY key DESC ALPHA" );
805 $db->lsort( "BY some_index DESC ALPHA" );
806 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 $db->lsort( "some_key", "BY key DESC" );
815 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 @items = $db->lsplice( "some_key", 20, 2, @list );
822 @items = $db->lsplice( "some_key", 20, 2 );
823 @items = $db->lsplice( "some_key", 20 );
824 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 @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 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 @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 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 @keys = $db->lvals( "key =~ /$pattern/" );
855 $len = $db->lvals( "key =~ /$pattern/" );
856 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 $val = $db->rpop( $key );
862 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 $len = $db->rpush( "some_key", "val1", "val2" );
868
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 lappend ( key, index, string )
875 Appends a value to key-index and returns its new length.
876 $len = $db->lappend( $key, 0, "foo" );
878 ldecr ( key, index )
880 Decrements the value of key-index by one and returns its new value.
881 $num = $db->ldecr( $key, 0 );
883 ldecrby ( key, index, number )
885 Decrements the value of key-index by the given number and returns its
886 new value.
887 $num = $db->ldecrby( $key, 0, 2 );
889 lgetdecr ( key, index )
891 Decrements the value of key-index by one and returns its old value.
892 $old = $db->lgetdecr( $key, 0 );
894 lgetincr ( key, index )
896 Increments the value of key-index by one and returns its old value.
897 $old = $db->lgetincr( $key, 0 );
899 lgetset ( key, index, value )
901 Sets the value of key-index and return its old value.
902 $old = $db->lgetset( $key, 0, "baz" );
904 lincr ( key, index )
906 Increments the value of key-index by one and returns its new value.
907 $num = $db->lincr( $key, 0 );
909 lincrby ( key, index, number )
911 Increments the value of key-index by the given number and returns its
912 new value.
913 $num = $db->lincrby( $key, 0, 2 );
915
917 The implementation is inspired by various Redis Hash/List primitives at
918 <http://redis.io/commands>.
919
921 MCE, MCE::Hobo, MCE::Shared
922
924 Mario E. Roy, <marioeroy AT gmail DOT com>
925perl v5.30.1 2020-01-30 MCE::Shared::Minidb(3)