Documentation Home
MySQL 5.6 リファレンスマニュアル
Download this Manual
PDF (US Ltr) - 26.8Mb
PDF (A4) - 26.9Mb
HTML Download (TGZ) - 7.1Mb
HTML Download (Zip) - 7.2Mb


16.6.3.3 C および C++ での libmemcached の使用

libmemcached ライブラリは、memcached に対する C および C++ インタフェースを提供し、いくつかの異なる追加 API 実装 (Perl、Python、および Ruby を含む) の基盤にもなります。libmemcached のコア関数を理解することは、こうしたほかのインタフェースを使用するときにも役立ちます。

C ライブラリは、memcached のもっとも包括的なインタフェースライブラリであり、libmemcached ライブラリをベースとしないインタフェースでは常時公開されていない関数と操作システムを提供します。

さまざまな関数を、その基本操作に応じて分類できます。コア API へのインタフェースとなる関数に加えて、いくつかのユーティリティー関数によって拡張機能 (データの末尾への追加や先頭への追加など) が提供されます。

libmemcached をビルドしてインストールするには、libmemcached パッケージをダウンロードし、configure を実行してから、ビルドおよびインストールします。

shell> tar xjf libmemcached-0.21.tar.gz
shell> cd libmemcached-0.21
shell> ./configure
shell> make
shell> make install

多くの Linux オペレーティングシステムでは、通常の yumapt-get、または同様のコマンドを使用すると、対応する libmemcached パッケージをインストールできます。

このライブラリを使用するアプリケーションをビルドするには、最初にサーバーリストを設定します。memcached_st メイン構造体の内部に構成されたサーバーを直接操作したり、サーバーリストを別個に移入したりして、そのリストを memcached_st 構造体に追加します。次の例では、後者の方法を使用しています。サーバーリストを設定したあとは、関数を呼び出してデータを格納または取得できます。事前設定値を localhost に設定する簡単なアプリケーションをここに示します。

#include <stdio.h>
#include <string.h>
#include <unistd.h>
#include <libmemcached/memcached.h>

int main(int argc, char *argv[])
{
  memcached_server_st *servers = NULL;
  memcached_st *memc;
  memcached_return rc;
  char *key= "keystring";
  char *value= "keyvalue";

  memcached_server_st *memcached_servers_parse (char *server_strings);
  memc= memcached_create(NULL);

  servers= memcached_server_list_append(servers, "localhost", 11211, &rc);
  rc= memcached_server_push(memc, servers);

  if (rc == MEMCACHED_SUCCESS)
    fprintf(stderr,"Added server successfully\n");
  else
    fprintf(stderr,"Couldn't add server: %s\n",memcached_strerror(memc, rc));

  rc= memcached_set(memc, key, strlen(key), value, strlen(value), (time_t)0, (uint32_t)0);

  if (rc == MEMCACHED_SUCCESS)
    fprintf(stderr,"Key stored successfully\n");
  else
    fprintf(stderr,"Couldn't store key: %s\n",memcached_strerror(memc, rc));

  return 0;
}

操作が成功したかどうかをテストするには、特定の関数の戻り値 (または移入された結果コード) を使用します。操作が成功した場合、この値は常に MEMCACHED_SUCCESS に設定されます。エラーが発生した場合は、memcached_strerror() 関数を使用して、結果コードを出力可能な文字列に変換します。

アプリケーションをビルドするには、memcached ライブラリを指定します。

shell> gcc -o memc_basic memc_basic.c -lmemcached

memcached サーバーを起動したあとで上記のサンプルアプリケーションを実行すると、成功メッセージが返されます。

shell> memc_basic
Added server successfully
Key stored successfully
16.6.3.3.1 libmemcached のベース関数

libmemcached のベース関数を使用すると、memcached サーバーとのインタフェースとして使用される memcached_st メイン構造体を作成、破壊、およびクローニングできます。主な関数の定義を次に示します。

memcached_st *memcached_create (memcached_st *ptr);

ほかの libmemcached API 関数で使用する新しい memcached_st 構造体を作成します。既存の静的な memcached_st 構造体を指定することも、NULL を指定して新しい構造体を割り当てることもできます。作成された構造体へのポインタを返します。失敗時は NULL を返します。

void memcached_free (memcached_st *ptr);

以前に作成された memcached_st 構造体に割り当てられていた構造体とメモリーを解放します。

memcached_st *memcached_clone(memcached_st *clone, memcached_st *source);

指定された source から既存の memcached 構造体をクローニングし、その構造体に定義されているデフォルトとサーバーリストをコピーします。

16.6.3.3.2 libmemcached のサーバー関数

libmemcached API は、memcached_server_st 構造体に格納されているサーバーリストを使用して、残りの関数で使用されるサーバーリストとして機能します。memcached を使用するには、最初にサーバーリストを作成し、次にそのサーバーリストを有効な libmemcached オブジェクトに適用します。

このサーバーリストとアクティブな libmemcached オブジェクト内のサーバーリストは別個に操作できるため、アクティブな libmemcached インタフェースの実行中にサーバーリストを更新および管理できます。

memcached_st 構造体内のサーバーリストを操作する関数は、次のとおりです。

memcached_return
   memcached_server_add (memcached_st *ptr,
                         char *hostname,
                         unsigned int port);

指定された hostname および port を使用して、ptr で指定された memcached_st 構造体にサーバーを追加します。

memcached_return
   memcached_server_add_unix_socket (memcached_st *ptr,
                                     char *socket);

memcached_st 構造体に構成されたサーバーリストに Unix ソケットを追加します。

unsigned int memcached_server_count (memcached_st *ptr);

memcached_st 構造体に含まれている構成済みサーバー数のカウントを返します。

memcached_server_st *
   memcached_server_list (memcached_st *ptr);

memcached_st 構造体に含まれる定義済みホストの配列を返します。

memcached_return
   memcached_server_push (memcached_st *ptr,
                          memcached_server_st *list);

現在の memcached_st 構造体に構成されているサーバーリストに対して既存のサーバーリストをプッシュします。これにより、既存のリストの末尾にサーバーが追加されますが、重複はチェックされません。

memcached_server_st 構造体を使用して memcached サーバーのリストを作成し、それらを memcached_st 構造体に個別に適用できます。

memcached_server_st *
   memcached_server_list_append (memcached_server_st *ptr,
                                 char *hostname,
                                 unsigned int port,
                                 memcached_return *error);

hostname および port を使用して、ptr のサーバーリストにサーバーを追加します。結果コードは error 引数によって処理されます。この引数は既存の memcached_return 変数を指します。この関数は返されたリストへのポインタを返します。

unsigned int memcached_server_list_count (memcached_server_st *ptr);

サーバーリスト内のサーバー数を返します。

void memcached_server_list_free (memcached_server_st *ptr);

サーバーリストに関連付けられたメモリーを解放します。

memcached_server_st *memcached_servers_parse (char *server_strings);

サーバーリストを含む文字列を解析します。個々のサーバーはカンマ、空白、またはその両方で区切られ、個々のサーバーは server[:port] という形式になっています。戻り値はサーバーリスト構造体です。

16.6.3.3.3 libmemcached の設定関数

libmemcached 内の設定関連関数は、memcached プロトコルでサポートされるコア関数と同じ機能を備えています。各種関数の完全な定義は、すべてのベース関数 (addreplaceprependappend) と同じです。たとえば、memcached_set() の関数定義は次のとおりです。

memcached_return
   memcached_set (memcached_st *ptr,
                  const char *key,
                  size_t key_length,
                  const char *value,
                  size_t value_length,
                  time_t expiration,
                  uint32_t flags);

ptrmemcached_st 構造体です。keykey_length はキーの名前と長さを定義し、valuevalue_length は対応する値と長さを定義します。失効およびオプションフラグを設定することもできます。詳細については、セクション16.6.3.3.5「libmemcached の動作の制御」を参照してください。

この表に、libmemcached の残りの設定関連関数と、memcached プロトコルでサポートされる同等のコア関数の概要を示します。

libmemcached の関数 同等のコア関数
memcached_set(memc, key, key_length, value, value_length, expiration, flags) 汎用の set() 操作。
memcached_add(memc, key, key_length, value, value_length, expiration, flags) 汎用の add() 関数。
memcached_replace(memc, key, key_length, value, value_length, expiration, flags) 汎用の replace()
memcached_prepend(memc, key, key_length, value, value_length, expiration, flags) 指定された value を指定された key の現在の値の前に追加します。
memcached_append(memc, key, key_length, value, value_length, expiration, flags) 指定された value を指定された key の現在の値のあとに追加します。
memcached_cas(memc, key, key_length, value, value_length, expiration, flags, cas) サーバー内の対応する cas 値が同じ場合は、特定のキーのデータを上書きします。
memcached_set_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) 汎用の set() とほぼ同じですが、個々のサーバーの識別に使用できる追加のマスターキーオプションを備えています。
memcached_add_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) 汎用の add() とほぼ同じですが、個々のサーバーの識別に使用できる追加のマスターキーオプションを備えています。
memcached_replace_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) 汎用の replace() とほぼ同じですが、個々のサーバーの識別に使用できる追加のマスターキーオプションを備えています。
memcached_prepend_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) memcached_prepend() とほぼ同じですが、個々のサーバーの識別に使用できる追加のマスターキーオプションを備えています。
memcached_append_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) memcached_append() とほぼ同じですが、個々のサーバーの識別に使用できる追加のマスターキーオプションを備えています。
memcached_cas_by_key(memc, master_key, master_key_length, key, key_length, value, value_length, expiration, flags) memcached_cas() とほぼ同じですが、個々のサーバーの識別に使用できる追加のマスターキーオプションを備えています。

by_key メソッドには、サーバー選択のハッシュ化段階で使用および適用されるマスターキーを定義する 2 つの引数が追加されています。これは、次の定義で確認できます。

memcached_return
   memcached_set_by_key(memcached_st *ptr,
                        const char *master_key,
                        size_t master_key_length,
                        const char *key,
                        size_t key_length,
                        const char *value,
                        size_t value_length,
                        time_t expiration,
                        uint32_t flags);

すべての関数が MEMCACHED_SUCCESS 定数と比較できる memcached_return 型の値を返します。

16.6.3.3.4 libmemcached の取得関数

libmemcached の関数は、1 つの項目への直接アクセスと、多数のキーを同時にフェッチするときの応答が非常に高速な複数キーの要求メカニズムを提供します。

汎用の get() と同等である主要な get スタイルの関数は、memcached_get() です。この関数は、指定されたキーに関連付けられた値を指す文字列ポインタを返します。

char *memcached_get (memcached_st *ptr,
                     const char *key, size_t key_length,
                     size_t *value_length,
                     uint32_t *flags,
                     memcached_return *error);

複数キーの get である memcached_mget() も使用可能です。複数キーの取得操作を使用すると、memcached_get() を個々に呼び出してキー値を取得するよりも、1 ブロックの操作を非常に高速に実行できます。複数キー取得を開始するには、memcached_mget() を呼び出します。

memcached_return
    memcached_mget (memcached_st *ptr,
                    char **keys, size_t *key_length,
                    unsigned int number_of_keys);

戻り値は操作の成功です。keys パラメータはキーを含む文字列の配列、key_length は対応する各キーの長さを含む配列です。number_of_keys は配列に設定したキーの数です。

個々の値をフェッチするには、memcached_fetch() を使用して対応する各値を取得します。

char *memcached_fetch (memcached_st *ptr,
                       const char *key, size_t *key_length,
                       size_t *value_length,
                       uint32_t *flags,
                       memcached_return *error);

この関数はキー値を返し、keykey_length、および value_length パラメータに対応するキーと長さの情報を移入します。この関数は、返す値がなくなったときに NULL を返します。キーデータの移入と情報の戻りを含む完全な例をここに示します。

#include <stdio.h>
#include <sstring.h>
#include <unistd.h>
#include <libmemcached/memcached.h>

int main(int argc, char *argv[])
{
  memcached_server_st *servers = NULL;
  memcached_st *memc;
  memcached_return rc;
  char *keys[]= {"huey", "dewey", "louie"};
  size_t key_length[3];
  char *values[]= {"red", "blue", "green"};
  size_t value_length[3];
  unsigned int x;
  uint32_t flags;

  char return_key[MEMCACHED_MAX_KEY];
  size_t return_key_length;
  char *return_value;
  size_t return_value_length;

  memc= memcached_create(NULL);

  servers= memcached_server_list_append(servers, "localhost", 11211, &rc);
  rc= memcached_server_push(memc, servers);

  if (rc == MEMCACHED_SUCCESS)
    fprintf(stderr,"Added server successfully\n");
  else
    fprintf(stderr,"Couldn't add server: %s\n",memcached_strerror(memc, rc));

  for(x= 0; x < 3; x++)
    {
      key_length[x] = strlen(keys[x]);
      value_length[x] = strlen(values[x]);

      rc= memcached_set(memc, keys[x], key_length[x], values[x],
                        value_length[x], (time_t)0, (uint32_t)0);
      if (rc == MEMCACHED_SUCCESS)
        fprintf(stderr,"Key %s stored successfully\n",keys[x]);
      else
        fprintf(stderr,"Couldn't store key: %s\n",memcached_strerror(memc, rc));
    }

  rc= memcached_mget(memc, keys, key_length, 3);

  if (rc == MEMCACHED_SUCCESS)
    {
      while ((return_value= memcached_fetch(memc, return_key, &return_key_length,
                                            &return_value_length, &flags, &rc)) != NULL)
        {
          if (rc == MEMCACHED_SUCCESS)
            {
              fprintf(stderr,"Key %s returned %s\n",return_key, return_value);
            }
        }
    }

  return 0;
}

上記のアプリケーションを実行すると、次の出力が生成されます。

shell> memc_multi_fetch
Added server successfully
Key huey stored successfully
Key dewey stored successfully
Key louie stored successfully
Key huey returned red
Key dewey returned blue
Key louie returned green
16.6.3.3.5 libmemcached の動作の制御

libmemcached の動作は、1 つ以上の動作フラグを設定することで変更できます。これらは、グローバルに設定するか、個々の関数の呼び出し中に適用できます。サーバーの選択時に使用されるハッシュ化メカニズムなど、追加の設定を受け入れる動作もあります。

グローバルな動作を設定するには:

memcached_return
   memcached_behavior_set (memcached_st *ptr,
                           memcached_behavior flag,
                           uint64_t data);

現在の動作設定を取得するには:

uint64_t
   memcached_behavior_get (memcached_st *ptr,
                           memcached_behavior flag);

libmemcached の動作フラグを次の表に示します。

動作 説明
MEMCACHED_BEHAVIOR_NO_BLOCK libmemcached で非同期 I/O を使用します。
MEMCACHED_BEHAVIOR_TCP_NODELAY ネットワークソケットの NODELAY をオンにします。
MEMCACHED_BEHAVIOR_HASH 値がない場合は、MD5 を使用してキー用のデフォルトのハッシュ化アルゴリズムを設定します。ほかの有効な値として、MEMCACHED_HASH_DEFAULTMEMCACHED_HASH_MD5MEMCACHED_HASH_CRCMEMCACHED_HASH_FNV1_64MEMCACHED_HASH_FNV1A_64MEMCACHED_HASH_FNV1_32、および MEMCACHED_HASH_FNV1A_32 があります。
MEMCACHED_BEHAVIOR_DISTRIBUTION 特定の値を格納するために使用されるサーバーの選択方法を変更します。デフォルトの方法は MEMCACHED_DISTRIBUTION_MODULA です。整合ハッシュ化を有効にするには、MEMCACHED_DISTRIBUTION_CONSISTENT を設定します。MEMCACHED_DISTRIBUTION_CONSISTENT は、値 MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA のエイリアスです。
MEMCACHED_BEHAVIOR_CACHE_LOOKUPS DNS サービスに対して行われたルックアップをキャッシュします。個々のホストに IP アドレスではなく名前を使用している場合は、これによってパフォーマンスが向上することがあります。
MEMCACHED_BEHAVIOR_SUPPORT_CAS CAS 操作をサポートします。パフォーマンスが低下するため、デフォルトではこれは無効になっています。
MEMCACHED_BEHAVIOR_KETAMA デフォルトの分布を MEMCACHED_DISTRIBUTION_CONSISTENT_KETAMA に設定し、ハッシュを MEMCACHED_HASH_MD5 に設定します。
MEMCACHED_BEHAVIOR_POLL_TIMEOUT poll() で使用されるタイムアウト値を変更します。タイムアウト値には signed int ポインタを指定します。
MEMCACHED_BEHAVIOR_BUFFER_REQUESTS I/O 要求を送信せずにバッファリングします。このデータは、取得操作または接続のクローズによってフラッシュされます。
MEMCACHED_BEHAVIOR_VERIFY_KEY 指定されたキーが有効かどうかを libmemcached が強制的に検証します。
MEMCACHED_BEHAVIOR_SORT_HOSTS 設定すると、memcached_st 構造体の構成済みホストのリストに追加されたホストが、ソートされた順序でホストリストに配置されます。これにより、整合ハッシュ化が有効になっている場合は、その動作が破棄されます。
MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT 非ブロックモードでは、これによってソケット接続中のタイムアウトの値が変更されます。
16.6.3.3.6 libmemcached のコマンド行ユーティリティー

libmemcached には、主要な C ライブラリインタフェースに加えて、memcached アプリケーションの操作やデバッグに役立ついくつかのコマンド行ユーティリティーも含まれています。

すべてのコマンド行ツールはいくつかの引数を受け入れますが、その中でもっとも重要なものは、情報を返すときに接続するサーバーのリストを指定する servers です。

主要なツールは次のとおりです。

  • memcat: 指定された各 ID の値をコマンド行に表示します。

    shell> memcat --servers=localhost hwkey
    Hello world
  • memcp: ファイル名をキーとして使用して、ファイルの内容をキャッシュにコピーします。

    shell> echo "Hello World" > hwkey
    shell> memcp --servers=localhost hwkey
    shell> memcat --servers=localhost hwkey
    Hello world
  • memrm: キャッシュから項目を削除します。

    shell> memcat --servers=localhost hwkey
    Hello world
    shell> memrm --servers=localhost hwkey
    shell> memcat --servers=localhost hwkey
  • memslap: 取得/設定および複数クライアントの操作をシミュレートして、1 つ以上の memcached サーバーに対する負荷をテストします。たとえば、取得操作を実行する 100 台のクライアントの負荷をシミュレートできます。

    shell> memslap --servers=localhost --concurrency=100 --flush --test=get
    memslap --servers=localhost --concurrency=100 --flush --test=get	Threads connecting to servers 100
    	Took 13.571 seconds to read data
  • memflush: memcached キャッシュの内容をフラッシュ (空に) します。

    shell> memflush --servers=localhost