Class: Depot

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Mod_Depot
Defined in:
lib/depot.rb

Overview

require ‘depot’ The library ‘depot’ should be included in application codes. An instance of the class ‘Depot’ is used as a database handle. ‘Depot’ performs Mix-in of ‘Enumerable’. Each method of ‘Depot’ throws an exception of ‘Depot::EANY’ or its sub classes when an error occurs: ‘Depot::ENOERR’, ‘Depot::EFATAL’, ‘Depot::EMODE’, ‘Depot::EBROKEN’, ‘Depot::EKEEP’, ‘Depot::ENOITEM’, ‘Depot::EALLOC’, ‘Depot::EMAP’, ‘Depot::EOPEN’, ‘Depot::ECLOSE’, ‘Depot::ETRUNC’, ‘Depot::ESYNC’, ‘Depot::ESTAT’, ‘Depot::ESEEK’, ‘Depot::EREAD’, ‘Depot::EWRITE’, ‘Depot::ELOCK’, ‘Depot::EUNLINK’, ‘Depot::EMKDIR’, ‘Depot::ERMDIR’ and ‘Depot::EMISC’.

Constant Summary collapse

MyMutex =

class constants

Mutex::new()

Instance Method Summary collapse

Instance Method Details

#bnum ⇒ Object

num = depot.bnum() Method: Get the number of the elements of the bucket array. The return value is the number of the elements of the bucket array An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



357
358
359
 
# File 'lib/depot.rb', line 357

def bnum()
  mod_bnum(@index)
end

#clear ⇒ Object

bool = depot.clear() Method: Delete all records. The return value is always true. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



197
198
199
200
201
202
203
204
205
 
# File 'lib/depot.rb', line 197

def clear
  MyMutex.synchronize() do
    iterinit()
    while(rnum() > 0)
      out(iternext())
    end
  end
  true
end

#close ⇒ Object

bool = depot.close() Method: Close the database handle. The return value is always true. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs. Because the region of a closed handle is released, it becomes impossible to use the handle. Updating a database is assured to be written when the handle is closed. If a writer opens a database but does not close it appropriately, the database will be broken.



125
126
127
128
129
130
131
132
133
 
# File 'lib/depot.rb', line 125

def close()
  MyMutex.synchronize() do
    begin
      mod_close(@index)
    ensure
      @index = -1
    end
  end
end

#each ⇒ Object Also known as: each_pair

depot.each() do |key, val| … end Iterator Method: Iterate a process with a pair of a key and a value of each record.



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
 
# File 'lib/depot.rb', line 401

def each()
  MyMutex.synchronize() do
    iterinit()
    while(true)
      begin
        break unless key = iternext()
        val = get(key)
      rescue ENOITEM
        break
      end
      yield(key, val)
    end
    iterinit()
  end
  self
end

#each_key ⇒ Object

depot.each_key() do |key| … end Iterator Method: Iterate a process with a key of each record.



426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
 
# File 'lib/depot.rb', line 426

def each_key()
  MyMutex.synchronize() do
    iterinit()
    while(true)
      begin
        break unless key = iternext()
      rescue ENOITEM
        break
      end
      yield(key)
    end
    iterinit()
  end
  self
end

#each_value ⇒ Object

depot.each_value() do |val| … end Iterator Method: Iterate a process with a value of each record.



445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
 
# File 'lib/depot.rb', line 445

def each_value()
  MyMutex.synchronize() do
    iterinit()
    while(true)
      begin
        break unless key = iternext()
        val = get(key)
      rescue ENOITEM
        break
      end
      yield(val)
    end
    iterinit()
  end
  self
end

#fatalerror ⇒ Object

bool = depot.fatalerror() Method: Check whether the database has a fatal error or not. The return value is true if the database has a fatal error, false if not. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



394
395
396
 
# File 'lib/depot.rb', line 394

def fatalerror()
  mod_fatalerror(@index)
end

#fetch(key, defval = nil) ⇒ Object Also known as: []

str = depot.fetch(key, defval) Method: Retrieve a record. ‘key’ specifies a key. Although it must be an instance of String, binary data is okey. ‘defval’ specifies the default value used when no record corresponds. If it is omitted, nil is specified. The return value is an instance of the value of the corresponding record, or the default value if no record corresponds. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/depot.rb', line 232

def fetch(key, defval = nil)
  if @silent
    if val = mod_get(@index, key, 0, -1)
      val
    else
      defval
    end
  else
    begin
      mod_get(@index, key, 0, -1)
    rescue ENOITEM
      defval
    end
  end
end

#fsiz ⇒ Object

num = depot.fsiz() Method: Get the size of the database file. The return value is the size of the database file. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



348
349
350
 
# File 'lib/depot.rb', line 348

def fsiz()
  mod_fsiz(@index)
end

#get(key, start = 0, max = -1)) ⇒ Object

str = depot.get(key, start, max) Method: Retrieve a record. ‘key’ specifies a key. Although it must be an instance of String, binary data is okey. ‘start’ specifies the offset address of the beginning of the region of the value to be read. If it is negative or omitted, the offset is specified as 0. ‘max’ specifies the max size to be read. If it is negative or omitted, the size to read is unlimited. The return value is an instance of the value of the corresponding record. If the silent flag is true and no record corresponds, nil is returned instead of exception. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs, no record corresponds, or the size of the value of the corresponding record is less than ‘max’.



219
220
221
 
# File 'lib/depot.rb', line 219

def get(key, start = 0, max = -1)
  mod_get(@index, key, start, max)
end

#index(val) ⇒ Object

str = depot.index(val) Method: Retrieve a record with a value. ‘val’ specifies a value. Although it must be an instance of String, binary data is okey. The return value is the key of the record with the specified value. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs or no record corresponds. If two or more records correspond, the first found record is selected.



504
505
506
507
508
509
510
511
512
513
514
515
 
# File 'lib/depot.rb', line 504

def index(val)
  key = nil
  MyMutex.synchronize() do
    iterinit()
    while(true)
      break unless key = iternext()
      (get(key) == val) && break
    end
    iterinit()
  end
  key
end

#iterinit ⇒ Object

bool = depot.iterinit() Method: Initialize the iterator of the database handle. The return value is always true. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs. The iterator is used in order to access the key of every record stored in a database.



272
273
274
 
# File 'lib/depot.rb', line 272

def iterinit()
  mod_iterinit(@index)
end

#iternext ⇒ Object

str = depot.iternext() Method: Get the next key of the iterator. The return value is the value of the next key. If the silent flag is true and no record corresponds, nil is returned instead of exception. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs or no record is to be get out of the iterator. It is possible to access every record by iteration of calling this method. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.



287
288
289
 
# File 'lib/depot.rb', line 287

def iternext()
  mod_iternext(@index)
end

#keys ⇒ Object

ary = depot.keys() Method: Get an array of all keys. The return value is an array of all keys. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



467
468
469
470
471
472
473
474
475
476
477
 
# File 'lib/depot.rb', line 467

def keys()
  ary = Array::new(rnum())
  MyMutex.synchronize() do
    iterinit()
    0.upto(ary.length - 1) do |i|
      ary[i] = iternext()
    end
    iterinit()
  end
  ary
end

#optimize(bnum = -1)) ⇒ Object

bool = depot.optimize(bnum) Method: Optimize the database. ‘bnum’ specifies the number of the elements of the bucket array. If it is omitted or not more than 0, the default value is specified. The return value is always true. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs. In an alternating succession of deleting and storing with overwrite or concatenate, dispensable regions accumulate. This method is useful to do away with them.



339
340
341
 
# File 'lib/depot.rb', line 339

def optimize(bnum = -1)
  mod_optimize(@index, bnum)
end

#out(key) ⇒ Object Also known as: delete

bool = depot.out(key) Method: Delete a record. ‘key’ specifies a key. Although it must be an instance of String, binary data is okey. The return value is always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs or no record corresponds.



183
184
185
 
# File 'lib/depot.rb', line 183

def out(key)
  mod_out(@index, key)
end

#put(key, val, dmode = DOVER) ⇒ Object Also known as: store, []=

bool = depot.put(key, val, dmode) Method: Store a record. ‘key’ specifies a key. Although it must be an instance of String, binary data is okey. ‘val’ specifies a value. Although it must be an instance of String, binary data is okey. ‘dmode’ specifies behavior when the key overlaps, by the following values: ‘Depot::DOVER’, which means the specified value overwrites the existing one, ‘Depot::DKEEP’, which means the existing value is kept, ‘Depot::DCAT’, which means the specified value is concatenated at the end of the existing value. If it is omitted, ‘Depot::DOVER’ is specified. The return value is always true. However, if the silent flag is true and replace is cancelled, false is returned instead of exception. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs or replace is cancelled.



161
162
163
 
# File 'lib/depot.rb', line 161

def put(key, val, dmode = DOVER)
  mod_put(@index, key, val, dmode)
end

#rnum ⇒ Object Also known as: length, size, to_int

num = depot.rnum() Method: Get the number of the records stored in the database. The return value is the number of the records stored in the database. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



366
367
368
 
# File 'lib/depot.rb', line 366

def rnum()
  mod_rnum(@index)
end

#setalign(align = 0) ⇒ Object

bool = depot.setalign(align) Method: Set alignment of the database handle. ‘align’ specifies the basic size of alignment. If it is omitted, alignment is cleared. The return value is always true. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs. If alignment is set to a database, the efficiency of overwriting values is improved. The size of alignment is suggested to be average size of the values of the records to be stored. If alignment is positive, padding whose size is multiple number of the alignment is placed. If alignment is negative, as ‘vsiz’ is the size of a value, the size of padding is calculated with ‘(vsiz / pow(2, abs(align) - 1))’. Because alignment setting is not saved in a database, you should specify alignment every opening a database.



303
304
305
 
# File 'lib/depot.rb', line 303

def setalign(align = 0)
  mod_setalign(@index, align)
end

#setfbpsiz(size = 0) ⇒ Object

bool = depot.setfbpsiz(size); Method: Set the size of the free block pool. ‘size’ specifies the size of the free block pool. If it is undef, the free block pool is not used. The return value is always true. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs. The default size of the free block pool is 16. If the size is greater, the space efficiency of overwriting values is improved with the time efficiency sacrificed.



316
317
318
 
# File 'lib/depot.rb', line 316

def setfbpsiz(size = 0)
  mod_setfbpsiz(@index, size)
end

#silent ⇒ Object 



144
145
146
 
# File 'lib/depot.rb', line 144

def silent
  @silent
end

#silent=(value) ⇒ Object

depot.silent = bool Method: Set the flag whether to repress frequent exceptions. The return value is the assigned value.



139
140
141
142
143
 
# File 'lib/depot.rb', line 139

def silent=(value)
  @silent = value ? true : false
  mod_setsilent(@index, silent ? 1 : 0)
  @silent
end

#sync ⇒ Object

bool = depot.sync() Method: Synchronize updating contents with the file and the device. The return value is always true. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs. This method is useful when another process uses the connected database file.



326
327
328
 
# File 'lib/depot.rb', line 326

def sync()
  mod_sync(@index)
end

#to_ary ⇒ Object Also known as: to_a

ary = depot.to_ary() Method: Get an array of alternation of each pair of a key and a value.



547
548
549
550
551
552
553
554
555
 
# File 'lib/depot.rb', line 547

def to_ary
  ary = Array::new(rnum())
  i = 0
  each() do |key, val|
    ary[i] = [key, val]
    i += 1
  end
  ary
end

#to_hash ⇒ Object Also known as: to_h

hash = depot.to_hash() Method: Get a hash storing all records.



565
566
567
568
569
570
571
 
# File 'lib/depot.rb', line 565

def to_hash
  hash = Hash::new()
  each() do |key, val|
    hash[key] = val
  end
  hash
end

#to_str ⇒ Object Also known as: to_s, inspect

str = depot.to_str() Method: Get string standing for the instance.



530
531
532
533
534
535
536
537
 
# File 'lib/depot.rb', line 530

def to_str
  if(@index != -1)
    sprintf("#<Depot:%#x:name=%s:state=open:bnum=%d:rnum=%d>",
            object_id(), @name, bnum(), rnum())
  else
    sprintf("#<Depot:%#x:name=%s:state=closed>", object_id(), @name)
  end
end

#values ⇒ Object

ary = depot.values() Method: Get an array of all values. The return value is an array of all values. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



484
485
486
487
488
489
490
491
492
493
494
 
# File 'lib/depot.rb', line 484

def values()
  ary = Array::new(rnum())
  MyMutex.synchronize() do
    iterinit()
    0.upto(ary.length - 1) do |i|
      ary[i] = get(iternext())
    end
    iterinit()
  end
  ary
end

#vsiz(key) ⇒ Object

num = depot.vsiz(key) Method: Get the size of the value of a record. ‘key’ specifies a key. Although it must be an instance of String, binary data is okey. The return value is the size of the value of the corresponding record. If the silent flag is true and no record corresponds, -1 is returned instead of exception. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs or no record corresponds. Because this method does not read the entity of a record, it is faster than ‘get’.



262
263
264
 
# File 'lib/depot.rb', line 262

def vsiz(key)
  mod_vsiz(@index, key)
end

#writable ⇒ Object

bool = depot.writable() Method: Check whether the database handle is a writer or not. The return value is true if the handle is a writer, false if not. An exception of ‘Depot::EANY’ or its sub classes is thrown if an error occurs.



385
386
387
 
# File 'lib/depot.rb', line 385

def writable()
  mod_writable(@index)
end