Class: Villa

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Mod_Villa
Defined in:
lib/villa.rb

Overview

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

Constant Summary collapse

MyMutex =

class constants

Mutex::new()

Instance Method Summary collapse

Instance Method Details

#clear ⇒ Object

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



217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/villa.rb', line 217

def clear
  MyMutex.synchronize() do
    begin
      while(rnum() > 0)
        curfirst();
        out(curkey())
      end
    rescue ENOITEM
    end
  end
  true
end

#close ⇒ Object

bool = villa.close() Method: Close the database handle. The return value is always true. An exception of ‘Villa::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. If the transaction is activated and not committed, it is aborted.



132
133
134
135
136
137
138
139
140
 
# File 'lib/villa.rb', line 132

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

#curfirst ⇒ Object

bool = villa.curfirst() Method: Move the cursor to the first record. 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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or there is no record in the database.



324
325
326
 
# File 'lib/villa.rb', line 324

def curfirst()
  mod_curfirst(@index)
end

#curjump(key, jmode = JFORWARD) ⇒ Object

bool = villa.curjump(key, jmode) Method: Move the cursor to a position around a record. ‘key’ specifies a key. Although it must be an instance of String, binary data is okey. ‘jmode’ specifies detail adjustment: ‘Villa::JFORWARD’, which means that the cursor is set to the first record of the same key and that the cursor is set to the next substitute if completely matching record does not exist, ‘Villa::JBACKWARD’, which means that the cursor is set to the last record of the same key and that the cursor is set to the previous substitute if completely matching record does not exist. If it is omitted, ‘Villa::JFORWARD’ is specified. 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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or there is no record corresponding the condition.



375
376
377
378
379
380
 
# File 'lib/villa.rb', line 375

def curjump(key, jmode = JFORWARD)
  if(@cmode == CMPOBJ)
    key = Marshal.dump(key)
  end
  mod_curjump(@index, key, jmode)
end

#curkey ⇒ Object

str = villa.curkey() Method: Get the key of the record where the cursor is. The return value is the key of the corresponding record. If the silent flag is true and no record corresponds, nil is returned instead of exception. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs or no record corresponds to the cursor.



389
390
391
392
393
394
395
 
# File 'lib/villa.rb', line 389

def curkey()
  key = mod_curkey(@index)
  if(@cmode == CMPOBJ && key)
    key = Marshal.load(key)
  end
  key
end

#curlast ⇒ Object

bool = villa.curlast() Method: Move the cursor to the last record. 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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or there is no record in the database.



335
336
337
 
# File 'lib/villa.rb', line 335

def curlast()
  mod_curlast(@index)
end

#curnext ⇒ Object

bool = villa.curnext() Method: Move the cursor to the next record. 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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or there is no next record.



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

def curnext()
  mod_curnext(@index)
end

#curout ⇒ Object

bool = villa.curout(); Method: Delete the record where the cursor is. The return value is always true. However, if the silent flag is true and no record corresponds to the cursor, false is returned instead of exception. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs or no record corresponds to the cursor. After deletion, the cursor is moved to the next record if possible.



440
441
442
 
# File 'lib/villa.rb', line 440

def curout()
  mod_curout(@index)
end

#curprev ⇒ Object

bool = villa.curprev() Method: Move the cursor to the previous record. 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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or there is no previous record.



346
347
348
 
# File 'lib/villa.rb', line 346

def curprev()
  mod_curprev(@index)
end

#curput(val, cpmode = CPCURRENT) ⇒ Object

bool = villa.curput(val, cpmode); Method: Insert a record around the cursor. ‘val’ specifies a value. Although it must be an instance of String, binary data is okey. ‘cpmode’ specifies detail adjustment: ‘Villa::CPCURRENT’, which means that the value of the current record is overwritten, ‘Villa::CPBEFORE’, which means that a new record is inserted before the current record, ‘Villa::CPAFTER’, which means that a new record is inserted after the current record. If it is omitted, ‘Villa::CPCURRENT’ is specified. The return value is always true. However, if the silent flag is true and no record corresponds to the cursor, false is returned instead of exception. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs or no record corresponds to the cursor. After insertion, the cursor is moved to the inserted record.



425
426
427
428
429
430
 
# File 'lib/villa.rb', line 425

def curput(val, cpmode = CPCURRENT)
  if(@cmode == CMPOBJ)
    val = Marshal.dump(val)
  end
  mod_curput(@index, val, cpmode)
end

#curval ⇒ Object

str = villa.curval() Method: Get the value of the record where the cursor is. The return value is 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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or no record corresponds to the cursor.



404
405
406
407
408
409
410
 
# File 'lib/villa.rb', line 404

def curval()
  val = mod_curval(@index)
  if(@cmode == CMPOBJ && val)
    val = Marshal.load(val)
  end
  val
end

#each ⇒ Object Also known as: each_pair

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



609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
 
# File 'lib/villa.rb', line 609

def each()
  MyMutex.synchronize() do
    curfirst()
    while(true)
      begin
        break unless key = curkey()
        val = curval()
        yield(key, val)
        curnext()
      rescue ENOITEM
        break
      end
    end
    curfirst()
  end
  self
end

#each_key ⇒ Object

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



635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
 
# File 'lib/villa.rb', line 635

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

#each_value ⇒ Object

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



655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
 
# File 'lib/villa.rb', line 655

def each_value()
  MyMutex.synchronize() do
    curfirst()
    while(true)
      begin
        break unless val = curval()
        curnext()
        yield(val)
      rescue ENOITEM
        break
      end
    end
    curfirst()
  end
  self
end

#fatalerror ⇒ Object

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



529
530
531
 
# File 'lib/villa.rb', line 529

def fatalerror()
  mod_fatalerror(@index)
end

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

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



260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/villa.rb', line 260

def fetch(key, defval = nil)
  if @silent
    if val = mod_get(@index, key)
      if(@cmode == CMPOBJ)
        val = Marshal.load(val)
      end
      val
    else
      defval
    end
  else
    begin
      val = mod_get(@index, key)
      if(@cmode == CMPOBJ)
        val = Marshal.load(val)
      end
      val
    rescue ENOITEM
      defval
    end
  end
end

#fsiz ⇒ Object

num = villa.fsiz() Method: Get the size of the database file. The return value is the size of the database file. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs. Because of the I/O buffer, the return value may be less than the real size.



492
493
494
 
# File 'lib/villa.rb', line 492

def fsiz()
  mod_fsiz(@index)
end

#get(key) ⇒ Object

str = villa.get(key) Method: Retrieve a record. ‘key’ specifies a key. Although it must be an instance of String, binary data is okey. 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. When the key of duplicated records is specified, the first record of the same key is deleted. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs or no record corresponds.



240
241
242
243
244
245
246
247
248
249
 
# File 'lib/villa.rb', line 240

def get(key)
  if(@cmode == CMPOBJ)
    key = Marshal.dump(key)
  end
  val = mod_get(@index, key)
  if(@cmode == CMPOBJ && val)
    val = Marshal.load(val)
  end
  val
end

#index(val) ⇒ Object

str = villa.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 ‘Villa::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.



722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
 
# File 'lib/villa.rb', line 722

def index(val)
  key = nil
  MyMutex.synchronize() do
    curfirst()
    while(true)
      break unless tmp = curval()
      if(tmp == val)
        key = curkey()
        break
      end
      curnext()
    end
    curfirst()
  end
  key
end

#keys ⇒ Object

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



677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
 
# File 'lib/villa.rb', line 677

def keys()
  ary = Array::new(rnum())
  MyMutex.synchronize() do
    begin
      curfirst()
      0.upto(ary.length - 1) do |i|
        ary[i] = curkey()
        curnext()
      end
      curfirst()
    rescue ENOITEM
    end
  end
  ary
end

#optimize ⇒ Object

bool = villa.optimize() Method: Optimize the database. The return value is always true. An exception of ‘Villa::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. This method should not be used while the transaction is activated.



482
483
484
 
# File 'lib/villa.rb', line 482

def optimize()
  mod_optimize(@index)
end

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

bool = villa.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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or no record corresponds. When the key of duplicated records is specified, the value of the first record of the same key is selected. The cursor becomes unavailable due to updating database.



200
201
202
203
204
205
 
# File 'lib/villa.rb', line 200

def out(key)
  if(@cmode == CMPOBJ)
    key = Marshal.dump(key)
  end
  mod_out(@index, key)
end

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

bool = villa.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: ‘Villa::DOVER’, which means the specified value overwrites the existing one, ‘Villa::DKEEP’, which means the existing value is kept, ‘Villa::DCAT’, which means the specified value is concatenated at the end of the existing value, ‘Villa::DDUP’, which means duplication of keys is allowed and the specified value is added as the last one, ‘Villa::DDUPR’, which means duplication of keys is allowed and the specified value is added as the first one. If it is omitted, ‘Villa::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 ‘Villa::EANY’ or its sub classes is thrown if an error occurs or replace is cancelled. The cursor becomes unavailable due to updating database.



172
173
174
175
176
177
178
 
# File 'lib/villa.rb', line 172

def put(key, val, dmode = DOVER)
  if(@cmode == CMPOBJ)
    key = Marshal.dump(key)
    val = Marshal.dump(val)
  end
  mod_put(@index, key, val, dmode)
end

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

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



501
502
503
 
# File 'lib/villa.rb', line 501

def rnum()
  mod_rnum(@index)
end

#settuning(lrecmax, nidxmax, lcnum, ncnum) ⇒ Object

bool = villa.settuning(lrecmax, nidxmax, lcnum, ncnum) Method: Set the tuning parameters for performance. ‘lrecmax’ specifies the max number of records in a leaf node of B+ tree. If it is not more than 0, the default value is specified. ‘nidxmax’ specifies the max number of indexes in a non-leaf node of B+ tree. If it is not more than 0, the default value is specified. ‘lcnum’ specifies the max number of caching leaf nodes. If it is not more than 0, the default value is specified. ‘ncnum’ specifies the max number of caching non-leaf nodes. If it is not more than 0, the default value is specified. The return value is always true. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs. The default setting is equivalent to ‘vlsettuning(49, 192, 1024, 512)’. Because tuning parameters are not saved in a database, you should specify them every opening a database.



459
460
461
 
# File 'lib/villa.rb', line 459

def settuning(lrecmax, nidxmax, lcnum, ncnum)
  mod_settuning(@index, lrecmax, nidxmax, lcnum, ncnum)
end

#silent ⇒ Object 



151
152
153
 
# File 'lib/villa.rb', line 151

def silent
  @silent
end

#silent=(value) ⇒ Object

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



146
147
148
149
150
 
# File 'lib/villa.rb', line 146

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

#sync ⇒ Object

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



470
471
472
 
# File 'lib/villa.rb', line 470

def sync()
  mod_sync(@index)
end

#to_ary ⇒ Object Also known as: to_a

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



769
770
771
772
773
774
775
776
777
 
# File 'lib/villa.rb', line 769

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



787
788
789
790
791
792
793
 
# File 'lib/villa.rb', line 787

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

#to_str ⇒ Object Also known as: to_s, inspect

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



752
753
754
755
756
757
758
759
 
# File 'lib/villa.rb', line 752

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

#tranabort ⇒ Object

bool = villa.tranabort() Method: Abort the transaction. The return value is always true. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs. Updating a database in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. Any other thread except for the one which began the transaction should not call this method.



576
577
578
579
580
581
582
 
# File 'lib/villa.rb', line 576

def tranabort()
  begin
    mod_tranabort(@index)
  ensure
    @tranmutex.unlock()
  end
end

#tranbegin ⇒ Object

bool = villa.tranbegin() Method: Begin the transaction. The return value is always true. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs. If a thread is already in the transaction, the other threads block until the prius is out of the transaction. Only one transaction can be activated with a database handle at the same time.



541
542
543
544
545
546
547
548
549
550
551
 
# File 'lib/villa.rb', line 541

def tranbegin()
  @tranmutex.lock()
  MyMutex.synchronize() do
    begin
      mod_tranbegin(@index)
    rescue
      @tranmutex.unlock()
      raise()
    end
  end
end

#trancommit ⇒ Object

bool = villa.trancommit() Method: Commit the transaction. The return value is always true. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs. Updating a database in the transaction is fixed when it is committed successfully. Any other thread except for the one which began the transaction should not call this method.



560
561
562
563
564
565
566
 
# File 'lib/villa.rb', line 560

def trancommit()
  begin
    mod_trancommit(@index)
  ensure
    @tranmutex.unlock()
  end
end

#transaction ⇒ Object

villa.transaction() do … end Iterator Method: Perform an iterator block in the transaction. The specified iterator block is performed in the transaction. If the block returns true, the transaction is committed. If the block returns false or raises any exception, the transaction is aborted.



590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
 
# File 'lib/villa.rb', line 590

def transaction()
  tranbegin()
  begin
    cmt = yield()
  rescue
    cmt = false
    raise()
  ensure
    if(cmt)
      trancommit()
    else
      tranabort()
    end
  end
end

#values ⇒ Object

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



698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
 
# File 'lib/villa.rb', line 698

def values()
  ary = Array::new(rnum())
  MyMutex.synchronize() do
    begin
      curfirst()
      0.upto(ary.length - 1) do |i|
        ary[i] = curval()
        curnext()
      end
      curfirst()
    rescue ENOITEM
    end
  end
  ary
end

#vnum(key) ⇒ Object

num = villa.vnum(key) Method: Get the number of records corresponding a key. ‘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 no record corresponds, 0 is returned. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs.



310
311
312
313
314
315
 
# File 'lib/villa.rb', line 310

def vnum(key)
  if(@cmode == CMPOBJ)
    key = Marshal.dump(key)
  end
  mod_vnum(@index, key)
end

#vsiz(key) ⇒ Object

num = villa.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. If multiple records correspond, the size of the first is returned. An exception of ‘Villa::EANY’ or its sub classes is thrown if an error occurs.



296
297
298
299
300
301
 
# File 'lib/villa.rb', line 296

def vsiz(key)
  if(@cmode == CMPOBJ)
    key = Marshal.dump(key)
  end
  mod_vsiz(@index, key)
end

#writable ⇒ Object

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



520
521
522
 
# File 'lib/villa.rb', line 520

def writable()
  mod_writable(@index)
end