Class: Curia

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Mod_Curia
Defined in:
lib/curia.rb

Overview

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

Constant Summary collapse

MyMutex =

class constants

Mutex::new()

Instance Method Summary collapse

Instance Method Details

#bnum ⇒ Object

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



361
362
363
 
# File 'lib/curia.rb', line 361

def bnum()
  mod_bnum(@index)
end

#clear ⇒ Object

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



200
201
202
203
204
205
206
207
208
 
# File 'lib/curia.rb', line 200

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

#close ⇒ Object

bool = curia.close() Method: Close the database handle. The return value is always true. An exception of ‘Curia::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.



128
129
130
131
132
133
134
135
136
 
# File 'lib/curia.rb', line 128

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

#each ⇒ Object Also known as: each_pair

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



405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/curia.rb', line 405

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

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



430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/curia.rb', line 430

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

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



449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
 
# File 'lib/curia.rb', line 449

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 = curia.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 ‘Curia::EANY’ or its sub classes is thrown if an error occurs.



398
399
400
 
# File 'lib/curia.rb', line 398

def fatalerror()
  mod_fatalerror(@index)
end

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

str = curia.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 ‘Curia::EANY’ or its sub classes is thrown if an error occurs.



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/curia.rb', line 235

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 = curia.fsiz() Method: Get the total size of the database files. The return value is the total size of the database files. An exception of ‘Curia::EANY’ or its sub classes is thrown if an error occurs. If the total size is more than 2GB, the return value overflows.



352
353
354
 
# File 'lib/curia.rb', line 352

def fsiz()
  mod_fsiz(@index)
end

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

str = curia.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 ‘Curia::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’.



222
223
224
 
# File 'lib/curia.rb', line 222

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

#index(val) ⇒ Object

str = curia.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 ‘Curia::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.



508
509
510
511
512
513
514
515
516
517
518
519
 
# File 'lib/curia.rb', line 508

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 = curia.iterinit() Method: Initialize the iterator of the database handle. The return value is always true. An exception of ‘Curia::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.



275
276
277
 
# File 'lib/curia.rb', line 275

def iterinit()
  mod_iterinit(@index)
end

#iternext ⇒ Object

str = curia.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 ‘Curia::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.



290
291
292
 
# File 'lib/curia.rb', line 290

def iternext()
  mod_iternext(@index)
end

#keys ⇒ Object

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



471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/curia.rb', line 471

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 = curia.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 ‘Curia::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.



342
343
344
 
# File 'lib/curia.rb', line 342

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

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

bool = curia.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 ‘Curia::EANY’ or its sub classes is thrown if an error occurs or no record corresponds.



186
187
188
 
# File 'lib/curia.rb', line 186

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

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

bool = curia.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: ‘Curia::DOVER’, which means the specified value overwrites the existing one, ‘Curia::DKEEP’, which means the existing value is kept, ‘Curia::DCAT’, which means the specified value is concatenated at the end of the existing value. If it is omitted, ‘Curia::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 ‘Curia::EANY’ or its sub classes is thrown if an error occurs or replace is cancelled.



164
165
166
 
# File 'lib/curia.rb', line 164

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

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

num = curia.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 ‘Curia::EANY’ or its sub classes is thrown if an error occurs.



370
371
372
 
# File 'lib/curia.rb', line 370

def rnum()
  mod_rnum(@index)
end

#setalign(align = 0) ⇒ Object

bool = curia.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 ‘Curia::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.



306
307
308
 
# File 'lib/curia.rb', line 306

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

#setfbpsiz(size = 0) ⇒ Object

bool = curia.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 ‘Curia::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.



319
320
321
 
# File 'lib/curia.rb', line 319

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

#silent ⇒ Object 



147
148
149
 
# File 'lib/curia.rb', line 147

def silent
  @silent
end

#silent=(value) ⇒ Object

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



142
143
144
145
146
 
# File 'lib/curia.rb', line 142

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

#sync ⇒ Object

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



329
330
331
 
# File 'lib/curia.rb', line 329

def sync()
  mod_sync(@index)
end

#to_ary ⇒ Object Also known as: to_a

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



551
552
553
554
555
556
557
558
559
 
# File 'lib/curia.rb', line 551

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 = curia.to_hash() Method: Get a hash storing all records.



569
570
571
572
573
574
575
 
# File 'lib/curia.rb', line 569

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 = curia.to_str() Method: Get string standing for the instance.



534
535
536
537
538
539
540
541
 
# File 'lib/curia.rb', line 534

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

#values ⇒ Object

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



488
489
490
491
492
493
494
495
496
497
498
 
# File 'lib/curia.rb', line 488

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 = curia.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 ‘Curia::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’.



265
266
267
 
# File 'lib/curia.rb', line 265

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

#writable ⇒ Object

bool = curia.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 ‘Curia::EANY’ or its sub classes is thrown if an error occurs.



389
390
391
 
# File 'lib/curia.rb', line 389

def writable()
  mod_writable(@index)
end