Build TOP Environments

開発者向け

C言語インタフェース

デバッグ関連(C I/F)
DSOロード関連(C I/F)
Create/Open/Close関連(C I/F)
トランザクション・アーカイブ関連(C I/F)
属性関連(C I/F)
GET関連(C I/F)
SET関連(C I/F)
リネーム関連(C I/F)
ダイレクトバイナリデータ取得/設定関連（C I/F）
削除関連(C I/F)
探索関連(C I/F)
ダイレクトアクセス関連(C I/F)
キュー関連(C I/F)
キュー（キー＆値）関連(C I/F)
ダンプ・ステータス関連(C I/F)

C++言語インタフェース

デバッグ関連(C/C++ I/F)
K2HashDynLibクラス
K2HTransDynLibクラス
K2HDAccessクラス
k2hstream（ik2hstream、ok2hstream）クラス
K2HArchiveクラス
K2HQueueクラス
K2HKeyQueueクラス
K2HShmクラス

C言語インタフェース

C言語用のインタフェースです。

開発時には以下のヘッダファイルをインクルードしてください。

#include <k2hash/k2hash.h>

リンク時には以下をオプションとして指定してください。

-lk2hash

以下にC言語用の関数の説明をします。

デバッグ関連(C I/F)

K2HASHライブラリは、内部動作およびAPIの動作の確認をするためにメッセージ出力を行うことができます。 本関数群は、メッセージ出力を制御するための関数群です。

書式

説明

返り値

k2h_set_debug_file、 k2h_unset_debug_file、k2h_load_debug_env、k2h_set_bumpup_debug_signal_user1 は成功した場合には、true を返します。失敗した場合には false を返します。

注意

環境変数 K2HDBGMODE、K2HDBGFILEについては、環境変数を参照してください。

サンプル

k2h_set_bumpup_debug_signal_user1();
k2h_set_debug_file("/var/log/k2hash/error.log");
k2h_set_debug_level_message();

DSOロード関連(C I/F)

K2HASHライブラリは、内部で利用するHASH関数およびトランザクション処理のための関数を外部のシェアードライブラリ（DSOモジュール）として読み込むことができます。 本関数群は、これらのシェアードライブラリのロード、アンロードを行う関数群です。

書式

説明

返り値

成功した場合には、true を返します。失敗した場合には false を返します。

注意

K2HASHは予めHASH関数（FNV-1A）、単純な処理を行うトランザクションプラグイン（Bultinトランザクションプラグイン）が組み込まれています。 本関数群によりDSOモジュールをロードした場合には、これら内部で実装されているHASH関数およびトランザクションプラグインより優先され、置き換えられます。

サンプル

if(!k2h_load_hash_library("/usr/lib64/myhashfunc.so")){
    return false;
}
if(!k2h_load_transaction_library("/usr/lib64/mytransfunc.so")){
    return false;
}
    //...
    //...
    //...
k2h_unload_hash_library();
k2h_unload_transaction_library();

Create/Open/Close関連(C I/F)

K2HASHファイル（もしくはオンメモリ）の初期化、オープン（アタッチ）、クローズ（デタッチ）を行う関数群です。

書式

説明

パラメータ

返り値

注意

各関数から返されるK2HASHハンドルは、他のAPI関数でK2HASHファイル（もしくはオンメモリ）を操作するために指定するハンドルです。 アタッチ（オープン）したK2HASHハンドルは必ずデタッチ（クローズ）してください。 MASK、CMASK、elementcntは、K2HASHライブラリが内部で管理しているデータツリーの構造（HASHテーブル）を決定する値です。付属しているk2hlintoolツールを試用して、その値の効果を試して、値を設定することを推奨します。 既に存在するK2HASHファイルをアタッチする場合は、これらの値は無視され、設定された値が使用されます。

サンプル

if(!k2h_create("/home/myhome/mydata.k2h", 8, 4, 1024, 512)){
    return false;
}
k2h_h k2handle;
if(K2H_INVALID_HANDLE == (k2handle = k2h_open_rw("/home/myhome/mydata.k2h", true, 8, 4, 1024, 512))){
    return false;
}
    //...
    //...
    //...
k2h_close(k2handle);

トランザクション・アーカイブ関連(C I/F)

K2HASHライブラリの提供するトランザクション処理に関連する関数群です。

書式

説明

パラメータ

返り値

注意

サンプル

if(!k2h_enable_transaction(k2handle, "/tmp/mytrans.log")){
    return false;
}
    //...
    //...
    //...
k2h_disable_transaction(k2handle);
   
//
// K2HASH can load the file which is made by transaction.
//
if(!k2h_load_archive(k2handle, "/tmp/mytrans.log", true)){
    return false;
}
// Full backup
if(!k2h_put_archive(k2handle, "/tmp/myfullbackup.ar", true)){
    return false;
}

属性関連(C I/F)

K2HASHライブラリの提供する属性（Attribute）に関連する関数群です。

書式

説明

パラメータ

返り値

成功した場合には、true を返します。失敗した場合には false を返します。

注意

Builtin属性の設定は、k2h_set_common_attr関数で行います。また、K2HASHライブラリは環境変数からBuiltin属性の設定値を読み出すこともできます。 まず、K2HASHライブラリの初期化時に環境変数から属性に関する設定値を読み込みます。その後、k2h_set_common_attr関数などの呼び出しによりBuiltin属性の設定は上書きされます。 よって、初期値（環境変数の設定含む）から変更しない値に関しては、NULL を指定することで初期値を維持できます。

サンプル

bool    is_mtime = true;
bool    is_defenc= true;
char*   passfile = "/etc/k2hpass";
bool    is_history = true;
time_t  expire = 120;
if(!k2h_set_common_attr(handle, &is_mtime, &is_defenc, passfile, &is_history, &expire)){
    return false;
}
    //...
    //...
    //...
k2h_clean_common_attr(k2handle);
   
if(!k2h_add_attr_plugin_library(k2handle, "/usr/lib/myattrs.so")){
    return false;
}
// Full backup
if(!k2h_put_archive(k2handle, "/tmp/myfullbackup.ar", true)){
    return false;
}

GET関連(C I/F)

K2HASHファイル（もしくはオンメモリ）からデータを読み出す関数群です。

書式

説明

パラメータ

返り値

k2h_get_trial_callback コールバック関数について

k2h_get_value*_ext、k2h_get_direct_value*_ext、k2h_get_str_value*_ext、k2h_get_str_direct_value*_ext関数は、引数にコールバック関数（k2h_get_trial_callback）を指定します。
k2h_get_trial_callback コールバック関数は、キー（Key）を読み出した時に、その値（Value）を引数に呼び出（コールバック）されます。
呼び出されたコールバック関数は、値（Value）を変更（上書き）することができます。
このコールバック関数を使うことにより、特定のキー（Key）に対する値（Value）を変更するタイミングが与えられます。
キー（Key）がK2HASHデータに存在していない場合もコールバック関数は呼び出されます。
たとえば、キー（Key）が未設定の場合、初期値としての値（Value）を返すことができます。これは、未設定のキー（Key）の読み出しにおいて、初期値を設定するタイミングを得ることができます。

コールバック関数は、以下のプロトタイプとなっています。

typedef K2HGETCBRES (*k2h_get_trial_callback)(const unsigned char* byKey, size_t keylen, const unsigned char* byValue, size_t vallen, unsigned char** ppNewValue, size_t* pnewvallen, const PK2HATTRPCK pattrs, int attrscnt, void* pExtData)

コールバック関数は、以下の引数と共に呼び出されます。

コールバック関数は以下の値を返します。

コールバック関数のサンプルを以下に示します。

static K2HGETCBRES GetTrialCallback(const unsigned char* byKey, size_t keylen, const unsigned char* byValue, size_t vallen, unsigned char** ppNewValue, size_t* pnewvallen, const PK2HATTRPCK pattrs, int attrscnt, void* pExtData)
{
    if(!byKey || 0 == keylen || !ppNewValue){
        return K2HGETCB_RES_ERROR;
    }
    //
    // Check get results which are byKey and byValue.
    // If you need to reset value for key, you set ppNewValue and return K2HGETCB_RES_OVERWRITE.
    // pExpData is the parameter when you call Get function.
    //
    return K2HGETCB_RES_NOTHING;
}

注意

取り出した値、サブキーリスト、属性の領域は専用の関数を使い、領域を開放してください。 各構造体の型を以下に示します。

サンプル

char* pval;
if(NULL == (pval = k2h_get_str_direct_value(k2handle, "mykey"))){
    return false;
}
printf("KEY=mykey has VALUE=%s\n", pval);
free(pval);

SET関連(C I/F)

K2HASHファイル（もしくはオンメモリ）にデータを書き込む関数群です。

書式

説明

パラメータ

返り値

成功した場合には、true を返します。失敗した場合には false を返します。

注意

K2HKEYPCK構造体は、以下の構造となっています。

サンプル

if(!k2h_set_str_value(k2handle, "mykey", "myval")){
    return false;
}

リネーム関連(C I/F)

K2HASHファイル（もしくはオンメモリ）のデータのキー名を変更（リネーム）する関数群です。

書式

説明

パラメータ

返り値

成功した場合には、true を返します。失敗した場合には false を返します。

サンプル

if(!k2h_rename_str(k2handle, "mykey", "newmykey")){
    return false;
}

ダイレクトバイナリデータ取得/設定関連（C I/F）

K2HASHファイル（もしくはオンメモリ）の複数のデータをHASH値等の範囲を指定して直接取得する関数群です。 本関数群は、複写（バックアップやレプリケーション）を目的として利用する特殊な関数群です。

書式

説明

パラメータ

注意

K2HBIN構造体

typedef struct k2hash_binary_data{
    unsigned char*    byptr;
    size_t            length;
}K2HBIN, *PK2HBIN;

返り値

成功した場合には、trueを返します。失敗した場合にはfalseを返します。

サンプル

if(!k2h_get_elements_by_hash(k2hash, hashval, startts, endts, target_hash, target_max_hash, target_hash_range, &nexthash, &pbindatas, &datacnt)){
     return false;
}
 
if(!k2h_set_element_by_binary(k2hash, &pbindatas[cnt], &ts)){
     return false;
}

削除関連(C I/F)

K2HASHファイル（もしくはオンメモリ）からデータを削除する関数群です。

書式

説明

パラメータ

返り値

成功した場合には、true を返します。失敗した場合には false を返します。

注意

k2h_remove_subkey、k2h_remove_str_subkey は、キーが指定されたサブキーを持っていない場合には失敗します。

サンプル

if(!k2h_remove_str_all(k2handle, "mykey")){
    return false;
}

探索関連(C I/F)

K2HASHファイル（もしくはオンメモリ）からデータを探索する関数群です。

書式

説明

パラメータ

返り値

注意

有効な探索ハンドル（k2h_find_h）を保持している期間（k2h_find_free により開放されるまでの期間）は、探索ハンドルが指し示しているK2HASHデータに対して読み取りのためのロックが設定されています。 ロックが設定されている期間は、そのキーの読み出し、書き込みがブロックされます。 よって、長期間この探索ハンドルを保持しないことを推奨します。 特に、探索ハンドルをキャッシュしたり、プログラム内部で長期間保持しないようにするべきです。

サンプル

// Full dump
for(k2h_find_h fhandle = k2h_find_first(k2handle); K2H_INVALID_HANDLE != fhandle; fhandle = k2h_find_next(fhandle)){
    char*    pkey = k2h_find_get_str_key(fhandle);
    char*    pval = k2h_find_get_direct_value(fhandle);
    printf("KEY=%s  --> VAL=%s\n", pkey ? pkey : "null", pval ? pval : "null");
    if(pkey){
        free(pkey);
    }
    if(pval){
        free(pval);
    }
}

ダイレクトアクセス関連(C I/F)

K2HASHファイル（もしくはオンメモリ）のデータへ直接アクセスする関数群です。 主に大きなサイズの値（Value）を持つデータへの読み書きを行う場合などに利用します。オフセットを指定して値（Value）の一部分の上書きや読み出しができます。

書式

説明

パラメータ

返り値

注意

サンプル

// get handle
k2h_da_h    dahandle;
if(K2H_INVALID_HANDLE == (dahandle = k2h_da_str_handle_write(k2handle, "mykey"))){
    fprintf(stderr, "Could not get k2h_da_h handle.");
    return false;
}
// offset
if(!k2h_da_set_write_offset(dahandle, 100)){
    fprintf(stderr, "Could not set write offset.");
    k2h_da_free(dahandle);
    return false;
}
// write
if(!k2h_da_set_value_str(dahandle, "test data")){
    fprintf(stderr, "Failed writing value.");
    k2h_da_free(dahandle);
    return false;
}
k2h_da_free(dahandle);

キュー関連(C I/F)

K2HASHライブラリは、キュー（FIFO/LIFO）としての機能を提供します。 キューは、値（Value）をFIFO/LIFOとして蓄積（PUSH）し、読み出し（POP）できます。 本関数群は、キューに関連する関数群です。

書式

説明

パラメータ

返り値

k2h_q_remove_trial_callback コールバック関数

k2h_q_remove_ext関数は、引数にコールバック関数（k2h_q_remove_trial_callback）を指定します。
コールバック関数は、キューの値の削除処理毎に呼び出され、値をキューから削除するか否かを判定することができます。
このコールバック関数により、キューに蓄積された値の削除において、任意の条件で削除を実行することができるようになります。

このコールバック関数は、以下のプロトタイプとなっています。

typedef K2HQRMCBRES (*k2h_q_remove_trial_callback)(const unsigned char* bydata, size_t datalen, const PK2HATTRPCK pattrs, int attrscnt, void* pExtData);

k2h_q_remove_ext関数は、キューの値の削除処理毎に指定されたコールバック関数を呼び出します。

コールバック関数は、以下の引数と共に呼び出されます。

コールバック関数は以下の値を返します。

コールバック関数のサンプルを以下に示します。

static K2HQRMCBRES QueueRemoveCallback(const unsigned char* bydata, size_t datalen, const PK2HATTRPCK pattrs, int attrscnt, void* pExtData)
{
    if(!bydata || 0 == datalen){
        return K2HQRMCB_RES_ERROR;
    }
    //
    // Check get queued data as bydata which is queued data(K2HQueue) or key(K2HKeyQueue).
    // If you need to remove it from queue, this function must return K2HQRMCB_RES_CON_RM or K2HQRMCB_RES_FIN_RM.
    // The other do not want to remove it, must return K2HQRMCB_RES_CON_NOTRM or K2HQRMCB_RES_FIN_NOTRM.
    // If you want to stop removing no more, this function can return K2HQRMCB_RES_FIN_*(RM/NOTRM).
    // pExpData is the parameter when you call Remove function.
    //
    return K2HQRMCB_RES_CON_RM;
}

注意

サンプル

if(!k2h_create("/home/myhome/mydata.k2h", 8, 4, 1024, 512)){
    return false;
}
k2h_h k2handle;
if(K2H_INVALID_HANDLE == (k2handle = k2h_open_rw("/home/myhome/mydata.k2h", true, 8, 4, 1024, 512))){
    return false;
}
// get queue handle
k2h_q_h    qhandle;
if(K2H_INVALID_HANDLE == (qhandle = k2h_q_handle_str_prefix(k2handle, true/*FIFO*/, "my_queue_prefix_"))){
    k2h_close(k2handle);
    return false;
}
// push
if(!k2h_q_str_push(qhandle, "test_value")){
    k2h_q_free(qhandle);
    k2h_close(k2handle);
    return false;
}
// pop
char*    pdata = NULL;
if(!k2h_q_str_pop(qhandle, &pdata)){
    k2h_q_free(qhandle);
    k2h_close(k2handle);
    return false;
}
free(pdata);
k2h_q_free(qhandle);
k2h_close(k2handle);

キュー（キー＆値）関連(C I/F)

K2HASHライブラリは、キュー（FIFO/LIFO）としての機能を提供します。 本関数群の提供するキューは、キー（Key）と値（Value）を1組として、FIFO/LIFOで蓄積（PUSH）し、読み出し（POP）できます。 本関数群は、このキーと値のキューに関連する関数群です。

書式

説明

パラメータ

返り値

注意

サンプル

if(!k2h_create("/home/myhome/mydata.k2h", 8, 4, 1024, 512)){
    return false;
}
k2h_h k2handle;
if(K2H_INVALID_HANDLE == (k2handle = k2h_open_rw("/home/myhome/mydata.k2h", true, 8, 4, 1024, 512))){
    return false;
}
// get queue handle
k2h_q_h    keyqhandle;
if(K2H_INVALID_HANDLE == (keyqhandle = k2h_keyq_handle_str_prefix(k2handle, , true/*FIFO*/, "my_queue_prefix_"))){
    k2h_close(k2handle);
    return false;
}
// push
if(!k2h_keyq_str_push_keyval(keyqhandle, "test_key", "test_value")){
    k2h_keyq_free(keyqhandle);
    k2h_close(k2handle);
    return false;
}
// test for accessing the key
char*    pvalue = NULL;
if(NULL == (pvalue = k2h_get_str_direct_value(k2handle, "test_key"))){
    // error...
}else{
    if(0 != strcmp(pvalue, "test_value")){
        // error...
    }
    free(pvalue);
}
// pop
char*    pkey = NULL;
pvalue        = NULL;
if(!k2h_keyq_str_pop_keyval(keyqhandle, &pkey, &pval)){
    k2h_q_free(keyqhandle);
    k2h_close(k2handle);
    return false;
}
if(0 != strcmp(pkey, "test_key") || 0 != strcmp(pvalue, "test_value")){
    // error...
}
free(pkey);
free(pvalue);
// check no key
pvalue = NULL;
if(NULL != (pvalue = k2h_get_str_direct_value(k2handle, "test_key"))){
    // error...
    free(pvalue);
}
free(pdata);
k2h_q_free(keyqhandle);
k2h_close(k2handle);

ダンプ・ステータス関連(C I/F)

K2HASHデータをダンプするためのデバッグ用の関数群です。

書式

説明

パラメータ

返り値

注意

サンプル

k2h_print_state(k2handle, NULL);
k2h_dump_full(k2handle, NULL);

C++言語インタフェース

K2HASHライブラリを利用するための、C++言語APIのI/Fです。

開発時には以下のヘッダファイルをインクルードしてください。

#include <k2hash/k2hash.h>
#include <k2hash/k2hshm.h>

リンク時には以下をオプションとして指定してください。

-lk2hash

以下にC++言語用の関数の説明をします。

デバッグ関連(C/C++ I/F)

K2HASHライブラリは、内部動作およびAPIの動作の確認をするためにメッセージ出力を行うことができます。 本関数群は、メッセージ出力を制御するための関数群です。

書式

説明

パラメータ

返り値

注意

K2HashDynLibクラス

説明

K2HASHライブラリは、内部で利用するHASH関数を外部のシェアードライブラリ（DSOモジュール）として読み込むことができます。 本クラスは、このシェアードライブラリのロード、アンロードを行う管理クラスです。 本クラスオブジェクトは K2HASHライブラリで唯一しか存在しないシングルトンとなっています。 本クラスのメソッドを利用する場合には、シングルトンの K2HashDynLibオブジェクトポインタを取得して利用してください。

HASH系関数プロトタイプ

DSOモジュールには、以下の3つの関数を含んでいる必要があります。

// First hash value returns, the value is used Key Index
k2h_hash_t k2h_hash(const void* ptr, size_t length);
 
// Second hash value returns, the value is used the Element in collision keys.
k2h_hash_t k2h_second_hash(const void* ptr, size_t length);
 
// Hash function(library) version string, the value is stamped into SHM file.
// This retuned value length must be under 32 byte.
const char* k2h_hash_version(void);

詳しくは、k2hashfunc.hを参照してください。

メソッド

メソッド説明

メソッド返り値

注意

シングルトンの取り扱いに注意してください。

サンプル

if(!K2HashDynLib::get()->Load("/home/myhome/myhashfunc.so")){
 exit(-1);
}
 ・
 ・
 ・
K2HashDynLib::get()->Unload();

K2HTransDynLibクラス

説明

K2HASHライブラリは、内部で利用するトランザクション処理を外部のシェアードライブラリ（DSOモジュール）として読み込むことができます。 本クラスは、このシェアードライブラリのロード、アンロードを行う管理クラスです。 本クラスオブジェクトは K2HASHライブラリで唯一しか存在しないシングルトンとなっています。 本クラスのメソッドを利用する場合には、シングルトンの K2HTransDynLibオブジェクトポインタを取得して利用してください。

トランザクション系関数プロトタイプ

DSOモジュールには、以下の3つの関数を含んでいる必要があります。

// transaction callback function
bool k2h_trans(k2h_h handle, PBCOM pBinCom);
 
// Transaction function(library) version string.
const char* k2h_trans_version(void);
 
// transaction control function
bool k2h_trans_cntl(k2h_h handle, PTRANSOPT pOpt);

詳しくは、k2htransfunc.hを参照してください。

メソッド

メソッド説明

メソッド返り値

注意

シングルトンの取り扱いに注意してください。

サンプル

if(!K2HTransDynLib::get()->Load("/home/myhome/mytransfunc.so")){
 exit(-1);
}
 ・
 ・
 ・
K2HTransDynLib::get()->Unload();

K2HDAccessクラス

説明

K2HASHファイル（もしくはオンメモリ）のデータへ直接アクセスするクラスです。 k2hshmクラスから、キー（Key）を指定して、このクラスのオブジェクトを取得し、利用できます。 主に大きなサイズの値（Value）を持つデータへの読み書きを行う場合などに利用します。オフセットを指定して値（Value）の一部分の上書きや読み出しができます。

メソッド

メソッド説明

メソッド返り値

注意

ダイレクトアクセスを利用した場合には、暗号化など属性（Attribute）の影響を受けません。 これは、例えば暗号化されたデータへの直接的なアクセスをすることを意味し、データそのものを破壊することになるため、属性を設定しているキーには利用しないようにしてください。

サンプル

k2hshm*    pk2hash;
    ・
    ・
    ・
 
// attach write object
K2HDAccess*    pAccess;
if(NULL == (pAccess = pk2hash->GetDAccessObj("mykey", K2HDAccess::WRITE_ACCESS, 0))){
    return false
}
 
// write
if(!pAccess->Write("my test data")){
    delete pAccess;
    return false;
}
delete pAccess;
 
// attach read object
if(NULL == (pAccess = pk2hash->GetDAccessObj("mykey", K2HDAccess::READ_ACCESS, 0))){
    return false
}
 
// read
unsigned char*    byValue   = NULL;
size_t        vallength = 20;        // this is about :-p
if(!pAccess->Read(&byValue, vallength)){
    delete pAccess;
    return false;
}
delete pAccess;
if(byValue){
    free(byValue);
}

k2hstream（ik2hstream、ok2hstream）クラス

説明

K2HASHファイル（もしくはオンメモリ）のデータへのアクセスを、iostreamとして取り扱うためのクラスです。 値（Value）への直接的なアクセス（読み込み、書き出し）を iostream 派生クラスとして実装しています。 k2hshmクラスとキー（Key）を指定し、ストリームクラス k2hstream、ik2hstream、ok2hstream を初期化し、iostream として利用できます。 std::stringstream と同等であり、また seekpos を利用できます。 詳細な説明は、std::stringstream などを参考にしてください。

基本クラス

k2hstream std::basic_stream
ik2hstreamstd::basic_istream
ok2hstreamstd::basic_ostream

サンプル

k2hshm*    pk2hash;
    ・
    ・
    ・
 
// output stream test
{
    ok2hstream    strm(pk2hash, "mykey");
    string        strTmp("test string");
 
    strm << strTmp << endl;
    strm << strTmp << ends;
 
    printf("output string     = \"%s\\n%s\\0\"", strTmp.c_str(), strTmp.c_str());
}
 
// input stream test
{
    ik2hstream    strm(pk2hash, "mykey");
    string        strTmp1;
    string        strTmp2;
 
    strm >> strTmp1;
    strm >> strTmp2;
 
    printf("string     = \"%s\",\"%s\"", strTmp1.c_str(), strTmp2.c_str());
 
    if(!strm.eof()){
        ・
        ・
        ・
    }
}

注意

本クラスが作成された時点（正確には本クラスを通してキー（Key）がオープンされた時点）で、キーに対してロックが発生します。 ik2hstream クラスではリードロック、ok2hstream および k2hstream クラスの場合にはライトロックが適応されます。 不要なロック状態を回避するために、本クラスは利用を完了した時点で、破棄するかクローズするべきです。

K2HArchiveクラス

説明

K2HASHデータをアーカイブするためのクラスです。 K2HShmクラスの管理するK2HASHデータを、K2HArchiveクラスがアーカイブ化します。

メソッド

メソッド説明

メソッド返り値

成功した場合には、true を返します。失敗した場合には false を返します。

サンプル

K2HArchive    archiveobj;
if(!archiveobj.Initialize("/tmp/k2hash.ar", false)){
    return false;
}
if(!archiveobj.Serialize(&k2hash, false)){
    return false;
}

K2HQueueクラス

説明

K2HASHライブラリは、キュー（FIFO/LIFO）としての機能を提供します。 キューは、値（Value）をFIFO/LIFOとして蓄積（PUSH）し、読み出し（POP）できます。 本クラスは、キュー（Queue）の操作を行うクラスです。 本クラスにより、キューへのデータの蓄積（push）と取り出し（pop）、削除を操作することができます。

K2HASHライブラリの提供するキューは、キー（Key）と値（Value）で実装されており、そのためキューに蓄積される内部的なキー名には特定のプレフィックスが付与されています。 プレフィックスの指定がされない場合には、”\0K2HQUEUE_PREFIX_“（先頭バイトが ‘\0’(0x00)であることに注意）がデフォルトとして使用されます。 Builtin属性を利用して、キューの暗号化、有効時間（Expire）を指定しできます。

メソッド

メソッド説明

メソッド返り値

注意

本クラスは操作クラスであり、クラスインスタンスを生成した時点では K2HASHデータへの操作は行いません。 実際の操作は、Push、Pop などのメソッドを実行したときに発生します。 キューに多量のデータが蓄積された状態で、K2HQueue::GetCount、K2HQueue::Readを 利用した場合、パフォーマンスはよくありません。 利用する場合は留意してください。

サンプル

k2hshm*    pk2hash;
    ・
    ・
    ・
  
// queue object
K2HQueue   myqueue(pk2hash, true/*FIFO*/, reinterpret_cast<const unsigned char*>("MYQUEUE_PREFIX_"), 15);  // without end of nil
// push
if(!myqueue.Push(reinterpret_cast<const unsigned char*>("test_data1"), 11) ||
   !myqueue.Push(reinterpret_cast<const unsigned char*>("test_data2"), 12) )
{
    return false
}
// pop
unsigned char* pdata   = NULL;
size_t         datalen = 0;
if(!myqueue.Pop(&pdata, datalen)){
    return false
}
free(pdata);
// remove
if(!myqueue.Remove(1)){
    return false
}

K2HKeyQueueクラス

説明

K2HASHライブラリは、キュー（FIFO/LIFO）としての機能を提供します。 本関数群の提供するキューは、キー（Key）と値（Value）を1組として、FIFO/LIFOで蓄積（PUSH）し、読み出し（POP）できます。 本クラスは、K2HQueueの派生クラスであり、このキー（Key）と値（Value）のキューをサポートするクラスになります。 キューに関連するキー名には、特定のプレフィックスがついており、K2HQueue と同じです。

本クラスにより、キューへのデータ（キー（Key）と値（Value））の蓄積（push）と取り出し（pop）、削除を操作することができます。 本クラスのキューに、キー（Key）と値（Value）を指定して蓄積（push）を行うと、K2HASHデータ内にキー（Key）と値（Value）が作成され、かつキューにキー（Key）が蓄積されます。 キューからの取り出し（pop）では、キー（Key）と値（Value）のセットで取り出すことが出来ます。（値（Value）だけの取り出しも可能です） キューからの取り出し（pop）を行った場合、キューからキー（Key）が削除され、かつK2HASHデータからキー（Key）と値（Value）のセットも削除されます。

本クラスにより、キー（Key）と値（Value）を K2HASHデータへ書き込みと同時に、その書き込み（更新した）順序を蓄積できます。 キューから取り出すことにより、キー（Key）と値（Value）を K2HASHデータから同時に消去（削除）ができます。

キューに蓄積されるキーと、そのキーと値はBuiltin属性を利用して暗号化、有効時間（Expire）の設定ができます。

メソッド

メソッド説明

メソッド返り値

注意

本クラスは、操作クラスであり、クラスインスタンスを生成した時点では K2HASHデータへの操作は行いません。実際の操作は、Push、Pop などのメソッドを実行したときに発生します。 キューに多量のデータが蓄積された状態で、K2HKeyQueue::GetCount、K2HKeyQueue::Read を利用した場合、パフォーマンスはよくありません。 利用する場合は留意してください。

サンプル

k2hshm*    pk2hash;
    ・
    ・
    ・
  
// queue object
K2HKeyQueue   myqueue(pk2hash, true/*FIFO*/, reinterpret_cast<const unsigned char*>("MYQUEUE_PREFIX_"), 15);  // without end of nil
// push
if(!myqueue.Push(reinterpret_cast<const unsigned char*>("test_key1"), 10, reinterpret_cast<const unsigned char*>("test_value1"), 12) ||
   !myqueue.Push(reinterpret_cast<const unsigned char*>("test_key2"), 10, reinterpret_cast<const unsigned char*>("test_value2"), 12) )
{
    return false
}
// pop
unsigned char* pkey     = NULL;
size_t         keylen   = 0;
unsigned char* pvalue   = NULL;
size_t         valuelen = 0;
if(!myqueue.Pop(&pkey, keylen, &pvalue, valuelen)){
    return false
}
free(pkey);
free(pvalue);
// remove
if(!myqueue.Remove(1)){
    return false
}

K2HShmクラス

説明

K2HASHデータの操作・実装クラスです。 このクラスを通じて、K2HASHデータの操作を行います。 C++言語における基本的なK2HASHデータの操作は、本クラスのインスタンスを作成した後で、全ての操作を行います。インスタンスは、K2HASHファイルもしくはオンメモリをオープン（アタッチ）して生成できます。 操作が完了したら（終了時）、クローズ（デタッチ）してください。

クラスメソッド

メソッド

メソッド説明

メソッド返り値

個々のプロトタイプを参照してください。 bool値の返り値のプロトタイプは、成功した場合には、true を返します。失敗した場合には false を返します。

サンプル

K2HShm    k2hash;
if(!k2hash.Attach("/tmp/myk2hash.k2h", false, true, false, true, 8, 4, 1024, 512)){
    exit(-1);
}
if(!k2hash.Set("my key", "my value")){
    k2hash.Detach();
    exit(-1);
}
char*    pValue = k2hash.Get("my key");
if(pValue){
    printf("my key = %s\n", pValue);
    free(pValue);
}
if(!k2hash.Dump(stdout, K2HShm::DUMP_PAGE_LIST)){
    k2hash.Detach();
    exit(-1);
}
k2hash.Detach();
Build TOP Environments