memcached

2008/5/26更新

対応バージョン: 0.21

libmemcachedに付属する各種ツールについて使用方法を説明する。

基本的に--serversで接続するサーバを指定する。サーバはカンマで区切って複数指定できる。ただし、特定のサーバに接続して処理をすべきツール(memrm,memcat,memcp)は複数指定しても最初の1台にだけ作用する。

memflush

指定したmemcached内のデータをすべて削除する。

例)

% memflush --servers=srv1,srv2

memslap

指定したmemcachedの負荷テストを行う。

デフォルトで10000回のテストを行うが、--execute-number=オプションで任意の回数を指定できる。その他いろいろなオプションがあるがここでは割愛する。

例)

% memslap --servers=srv1,srv2 --execute-number=30000
Threads connecting to servers 1
Took 4.791 seconds to load data

memerror

memcachedのエラーコードの意味を表示する。

例)

% memerror 1
FAILURE

% memerror 2
HOSTNAME LOOKUP FAILURE

memcached-1.2.5の場合、エラーコードは32個定義されている。

 1:FAILURE
 2:HOSTNAME LOOKUP FAILURE
 3:CONNECTION FAILURE
 4:CONNECTION BIND FAILURE
 5:WRITE FAILURE
 6:READ FAILURE
 7:UNKNOWN READ FAILURE
 8:PROTOCOL ERROR
 9:CLIENT ERROR
10:SERVER ERROR
11:CONNECTION SOCKET CREATE FAILURE
12:CONNECTION DATA EXISTS
13:CONNECTION DATA DOES NOT EXIST
14:NOT STORED
15:STORED
16:NOT FOUND
17:MEMORY ALLOCATION FAILURE
18:PARTIAL READ
19:SOME ERRORS WERE REPORTED
20:NO SERVERS DEFINED
21:SERVER END
22:SERVER DELETE
23:SERVER VALUE
24:STAT VALUE
25:SYSTEM ERROR
26:COULD NOT OPEN UNIX SOCKET
27:ACTION NOT SUPPORTED
28:A KEY LENGTH OF ZERO WAS PROVIDED
29:FETCH WAS NOT COMPLETED
30:A TIMEOUT OCCURRED
31:ACTION QUEUED
32:A BAD KEY WAS PROVIDED/CHARACTERS OUT OF RANGE

memrm

指定したmemcachedから特定のキーのデータを削除する。

例)

% memrm --servers=srv1 foo

指定したキーのデータが存在しない場合は以下のようなメッセージが返る。

memrm: foo: memcache error NOT FOUND

memstat

指定したmemcachedの利用状況をレポートする。

例)

% memstat --servers=srv1,srv2
Listing 2 Server

Server: srv1 (11211)
         pid: 17581
         uptime: 127562
         time: 1200116116
         version: 1.2.5
         pointer_size: 32
         rusage_user: 0.492925
         rusage_system: 1.141826
         curr_items: 101
         total_items: 101
         bytes: 0
         curr_connections: 0
         total_connections: 0
         connection_structures: 3
         cmd_get: 100
         cmd_set: 101
         get_hits: 100
         get_misses: 0
         evictions: 0
         bytes_read: 0
         bytes_written: 0
         limit_maxbytes: 67108864
         threads: 0

Server: srv2 (11211)
         pid: 18052
         uptime: 148
         time: 1200113846
         version: 1.2.5
         pointer_size: 32
         rusage_user: 0.0
         rusage_system: 0.0
         curr_items: 1
         total_items: 1
         bytes: 0
         curr_connections: 0
         total_connections: 0
         connection_structures: 2
         cmd_get: 2
         cmd_set: 1
         get_hits: 1
         get_misses: 1
         evictions: 0
         bytes_read: 0
         bytes_written: 0
         limit_maxbytes: 67108864
         threads: 0

memcat

指定したmemcachedに格納されている特定のキーのデータを表示する。

例)

% memcat --servers=srv1 foo
abcde

指定したキーのデータが存在しない場合は何も表示されない。

memcp

memcachedに定義するデータをファイルから取り込む。

ファイル名がキーとなり、ファイル中に記述した文字列がデータとなる。

--set、--add、--replaceにてデータの格納方法を指定し、--flag、--expireにて格納データへのオプションを指定する。

例)

% echo -n 123 > foo
% echo -n abcde > bar

% memcp --servers=srv1 --set foo bar

% memcat --servers=srv1 foo
123
% memcat --servers=srv1 bar
abcde

(*) ファイル中に改行コードを入れるとその文字も1文字と数えられてしまうので注意が必要である。ここでは「echo -n」として改行コードを入れないようにしている。

関連資料・記事

2008/5/21更新

対応バージョン: 1.2.5

memcachedで使用可能なコマンドには以下の種類がある。

set / get

データの格納 / 取得

gets

データの取得(後述のcas ID付)

replace

既存のデータの変更

append

既存のデータの後ろにデータを追加

prepend

既存のデータの前にデータを追加

cas

キーとcas IDのペアで既存のデータを特定して内容を変更

incr / decr

既存のデータの加算/減算

delete

データの削除

stats

サーバの利用状況のレポート

コマンドは以下のフォーマットで指定する。

set, replace, append, prepend
<コマンド> <キー> <フラグ> <有効期間> <サイズ>
cas
<コマンド> <キー> <フラグ> <有効期間> <サイズ> <cas ID>
incr, decr
<コマンド> <キー> <値>
get, gets, delete
<コマンド> <キー>
stats

引数なし

<フラグ>はデータの圧縮指定で、1:zip圧縮/0:非圧縮のどちらかを指定する。 <有効期間>はUNIXタイムスタンプ形式か現在からの秒数を指定することが可能である。ただし後者の場合は秒数が2592000 = 60 * 60 * 24 * 30 (30日)を超えることはできない。また0を指定すれば有効期限なしの意味になる。 <サイズ>は格納したいデータ長をバイト単位で指定する。 は特定のキーのある時期のデータに対する一意のシーケンス番号である。詳しくは後述する。

以下、それぞれの実行例を示す。

set / get

指定したキーに対してデータを格納/取得する。

例) 「foo」というキーに「123」という3バイトのデータを非圧縮/無期限で格納

set foo 0 0 3
123

=> STORED

get foo

=> VALUE foo 0 3
=> 123
=> END

gets

setで格納したデータを取り出す。

getと似ているが、データの他にcas IDを取得して後述のcasコマンドと合わせて使用する。

gets foo

=> VALUE foo 0 3 7 (7がcas ID)
=> 123
=> END

replace

既に格納されているデータを書き換える。

replace foo 0 0 3
abc

=> STORED

get foo

=> VALUE foo 0 3
=> abc
=> END

append

既に格納されているデータの後ろにデータを追加する。

append foo 0 0 3
999

=> STORED

get foo

=> VALUE foo 0 6
=> abc999
=> END

prepend

既に格納されているデータの前にデータを追加する。

prepend foo 0 0 3
111

=> STORED

get foo

=> VALUE foo 0 9
=> 111abc999
=> END

cas

getsでcas ID付で取得したデータに対して更新を行う。

あるキーのデータを書き換えるにはreplaceを使用してもよいが、この方法だと例えばユーザ1があるキーのデータを使用していて処理が終了したら別のデータに書き換えたい場合に途中で他のユーザがそのデータを書き換えてもそれを知るには再度getを行って以前取得したデータと同じかどうかを比較する必要がある。

このような煩雑な作業を避けるためにcasを使用する。

まずgetsでcas ID付のデータを取得しておき、処理終了後にデータを書き換える際にcas IDとともにcasコマンドを使用することにより、もし途中でデータが変わっていたら内部のcas IDも変わっているため更新ができなくなる(EXISTが返る)。

これにより自分が取得したデータに対してのみ書き換え行為が行われるようになり、途中で書き換えたデータが失われることがなくなる。

例) あるユーザがデータを取得してから内容を書き換えるまでに他のユーザによって書き換えられなかった場合

gets foo

=> VALUE foo 0 3 7
=> 123
=> END

(なんらかの処理)

cas foo 0 0 3 7
456

=> STORED ← cas IDが変わっていないので書き換えは成功する

例) あるユーザがデータを取得してから内容を書き換えるまでの間に別のユーザがデータを書き換えた場合

(ユーザ1がデータを取得)

gets foo

=> VALUE foo 0 3 8
=> 456
=> END

(ユーザ2によるデータ書き換え)

replace foo 0 0 3
abc

=> STORED ← 別ユーザがデータを書き換えた(この時点でcas IDは変わっている)

(ユーザ1によるデータ書き換え)

cas foo 0 0 3 8
zzz

=> EXISTS ← 既に他のユーザがデータを書き換えたのでzzzは書き込めない

get foo

=> VALUE foo 0 3
=> abc ← ユーザ2が書き換えたデータのまま
=> END

incr / decr

既存のデータの加算/減算を行う。

get foo

=> VALUE foo 0 3
=> 100
=> END

incr foo 3

=> 103

decr foo 5

=> 98

delete

指定したキーのデータを削除する。

delete foo

=> DELETED

get foo

=> END

stats

サーバの利用状況をレポートする。

stats

=> STAT pid 29456
=> STAT uptime 8305
=> STAT time 1211193200
=> STAT version 1.2.5
=> STAT pointer_size 32
=> STAT rusage_user 0.001999
=> STAT rusage_system 0.004999
=> STAT curr_items 2
=> STAT total_items 17
=> STAT bytes 108
=> STAT curr_connections 3
=> STAT total_connections 7
=> STAT connection_structures 4
=> STAT cmd_get 26
=> STAT cmd_set 19
=> STAT get_hits 22
=> STAT get_misses 4
=> STAT evictions 0
=> STAT bytes_read 820
=> STAT bytes_written 902
=> STAT limit_maxbytes 67108864
=> STAT threads 1
=> END

2008/7/4更新

対応バージョン: 1.24

公式サイト

準備

あらかじめインストールしておくもの

memcached

関連資料・記事

導入OS

Fedora 9

インストール

配布ファイル展開

% tar zxvf Cache-Memcached-1.24.tar.gz 
% cd Cache-Memcached-1.24

make,インストール

% perl Makefile.PL 
% make
% sudo make install

インストール物 (man,infoは除く)

/usr/lib/perl5/site_perl/5.10.0/Cache/Memcached.pm
/usr/lib/perl5/site_perl/5.10.0/Cache/Memcached/GetParser.pm

動作確認

以下のようなプログラムを書いてmemcachedに値を格納してみる。

use Cache::Memcached;

my $server   = "127.0.0.1"; # サーバ(IPアドレス)
my $port     = 11211;       # サーバ(ポート)
my $compress = 0;           # 圧縮指定(0:非圧縮)

my $key      = "foo";       # キー
my $value    = 123;         # 値
my $expires  = 600;         # 有効期間(秒)

my $memcached = new Cache::Memcached
{
  'servers' => ["${server}:${port}"],
  'compress_threshold' => $compress
};

$memcached->set($key, $value, $expires);

次に別のプログラムを書いて上記で格納した値が取り出せることを確認する。

use Cache::Memcached;

my $server   = "127.0.0.1"; # サーバ(IPアドレス)
my $port     = 11211;       # サーバ(ポート)

my $key      = "foo";       # キー

my $memcached = new Cache::Memcached
{
  'servers' => ["${server}:${port}"]
};

my $value = $memcached->get($key);

print "$value\n";

=> 123

その他、以下のようなメソッドが使用できる。

set_servers

接続先サーバを複数指定

例)

@server_list = ("127.0.0.1:11211", "192.168.0.1:11211");
$memcached->set_servers(\@server_list);
add

指定したキーのデータが「存在しない」場合のみ値をセット(パラメータはsetと同じ)

replace

指定したキーのデータが「存在する」場合のみ値をセット(パラメータはsetと同じ)

get_multi

指定した複数キーのデータを一度に取得

例)

@key_list = ("foo", "bar");
my $value = $memcached->get_multi(@key_list);

foreach $key (@key_list)
{
  print "$value->{$key}\n";
}
incr

指定したキーのデータを加算

例)

$memcached->incr("foo");     # +1 (インクリメント)
$memcached->incr("foo", 2);  # +2
decr

指定したキーのデータを減算

例)

$memcached->decr("foo");     # -1 (デクリメント)
$memcached->decr("foo", 2);  # -2
delete

指定したキーのデータを削除

例)

$memcached->delete("foo");

関連資料・記事

2007/12/11更新

対応バージョン: 1.5.0

公式サイト

準備

あらかじめインストールしておくもの

memcached

関連資料・記事

導入OS

Fedora 8

インストール

インストール

# gem install memcache-client

インストール物 (man,infoは除く)

/usr/lib/ruby/gems/1.8/gems/memcache-client-1.5.0/*/*

動作確認

以下のようなプログラムを書いてmemcachedに値を格納してみる。

require 'rubygems'
require 'memcache'

cache = MemCache.new('localhost:11211')

cache['num']   = 123                       # 数値
cache['str']   = 'abc'                     # 文字列
cache['array'] = [11, 22, 33]              # 配列
cache['hash']  = {1 => 'xxx', 2 => 'yyy'}  # ハッシュ

次に別のプログラムを書いて上記で格納した値が取り出せることを確認する。

require 'rubygems'
require 'memcache'

cache = MemCache.new('localhost:11211')

p cache['num']
p cache['str']
p cache['array']
p cache['hash']

=> 123
=> "abc"
=> [11, 22, 33]
=> {1=>"xxx", 2=>"yyy"}

関連資料・記事

2008/5/25更新

対応バージョン: 0.21

公式サイト

準備

あらかじめインストールしておくもの

memcached

関連資料・記事

導入OS

Fedora 9

インストール

配布ファイル展開

% tar zxvf libmemcached-0.21.tar.gz
% cd libmemcached-0.21.tar.gz

make,インストール

% ./configure
% make
% sudo make install

インストール物 (man,infoは除く)

/usr/local/bin/memcat
/usr/local/bin/memcp
/usr/local/bin/memerror
/usr/local/bin/memflush
/usr/local/bin/memrm
/usr/local/bin/memslap
/usr/local/bin/memstat

/usr/local/lib/libmemcached.*

/usr/local/lib/pkgconfig/libmemcached.pc

/usr/local/include/libmemcached/memcached.h

/usr/local/bin配下にインストールされる各ツールの使用法については以下を参照。

関連資料・記事

2008/9/1更新

対応バージョン: 1.2.6

公式サイト

準備

あらかじめインストールしておくもの

libevent

導入OS

Mac OS X 10.5(Leopard)
Fedora 9

管理用アカウント作成

memcachedはrootで実行できないので既存のアカウントで実行するか専用のアカウントを用意してそのアカウントで実行する。ここでは専用のアカウントを作成する。

(Mac OS X)

% sudo dscl . -list /Groups PrimaryGroupID | sort -k 2 -n (空きGIDを調べる)
% sudo dscl . -create /Groups/memcached PrimaryGroupID <GID>

% sudo dscl . -list /Users UniqueID | sort -k 2 -n (空きUIDを調べる)
% sudo dscl . -create /Users/memcached
% sudo dscl . -create /Users/memcached RealName memcached
% sudo dscl . -create /Users/memcached UniqueID <UID>
% sudo dscl . -create /Users/memcached PrimaryGroupID <GID>
% sudo dscl . -create /Users/memcached UserShell /sbin/nologin
% sudo dscl . -create /Users/memcached Password '*'

関連資料・記事

(Fedora)

% sudo groupadd memcached
% sudo useradd -g memcached -s /sbin/nologin -d /nonexistent memcached

インストール

配布ファイル展開

% tar zxvf memcached-1.2.6.tar.gz
% cd memcached-1.2.6

make,インストール

% ./configure
% make
% sudo make install

インストール物 (man,infoは除く)

/usr/local/bin/memcached
/usr/local/bin/memcached-debug

動作確認

memcachedを起動する。

% memcached -u memcached -d

まずは-dオプションにてデーモンモードでmemcachedを起動する。

その他、主なオプションを以下に示す。

-m <キャッシュメモリ容量>

デフォルトは64(単位はMB)。

-l <待ち受けネットワークインタフェース>

デフォルトはINDRR_ANY。

-p

デフォルトは11211。

-u <デーモン実行ユーザ>

rootでデーモンを起動する際にデーモン実行ユーザを指定する。

例) キャッシュ = 1GB、接続許可ホスト = ローカルホスト

% memcached -u memcached -d -m 1024 -l 127.0.0.1

次にmemcachedに接続する。

statsコマンドにてmemcachedの動作状況を確認する。

% telnet localhost 11211
stats
STAT pid 34304
STAT uptime 26
STAT time 1220202726
STAT version 1.2.6
STAT pointer_size 32
STAT rusage_user 0.000660
STAT rusage_system 0.001495
STAT curr_items 0
STAT total_items 0
STAT bytes 0
STAT curr_connections 3
STAT total_connections 4
STAT connection_structures 4
STAT cmd_get 0
STAT cmd_set 0
STAT get_hits 0
STAT get_misses 0
STAT evictions 0
STAT bytes_read 7
STAT bytes_written 0
STAT limit_maxbytes 67108864
STAT threads 1
END

上記のような結果が返ってくれば正常に動作している。接続を切断するには「quit」と入力する。

memcachedに接続したら実際に値の格納/取得を行ってみる。

コマンドには様々な種類があるが、ここではset(値の格納)とget(値の取得)を使ってみる.

コマンドは以下のフォーマットで指定する。

<コマンド> <キー> <圧縮フラグ(1 or 0)> <有効期間(単位:秒)> <サイズ(単位:Bytes)>

例) 「foo」というキーに「123」という3バイトのデータを非圧縮(0)/無期限(0)で格納する。またそれを取り出す。

set foo 0 0 3
123

=> STORED

get foo

=> VALUE foo 0 3
=> 123
=> END

quit

コマンド一覧は以下を参照。

関連資料・記事

memcachedを終了する。

単にkillすればよい。

% sudo killall memcached

memcached起動設定

ここでは起動オプションを以下のとおりとする。

起動モード

-d (デーモンモード)

デーモン実行ユーザ

memcached

キャッシュサイズ

64(MB)

plist作成(Mac OS X)

/Library/LaunchDaemons/memcached.plistを作成する。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>Label</key>
        <string>memcached</string>
        <key>ProgramArguments</key>
        <array>
                <string>/usr/local/bin/memcached</string>
                <string>-d</string>
                <string>-u</string>
                <string>memcached</string>
                <string>-m</string>
                <string>64</string>
        </array>
</dict>
</plist>

initスクリプト作成(Fedora)

/etc/rc.d/init.d/memcachedを作成する。

#!/bin/bash
#
# memcached
#
# chkconfig: 345 80 20
# description: memcached

TARGET=memcached
DST_BIN=/usr/local/bin/${TARGET}
EXEC_USER=memcached
CACHE_SIZE=64

start()
{
  echo -n "Starting ${TARGET}: "
  ${DST_BIN} -d -u ${EXEC_USER} -m ${CACHE_SIZE}
  echo
}

stop()
{
  echo -n "Shutting down ${TARGET}: "
  killall ${TARGET}
  echo
}

case "$1" in
  start)
    start
    ;;

  stop)
    stop
    ;;

  restart)
    stop
    start
    ;;

  *)
    echo "Usage: `basename $0` {start|stop|restart}" >&2
    exit 1
esac

exit 0

サービス登録/起動

(Mac OS X)

% sudo launchctl load /Library/LaunchDaemons/memcached.plist
% sudo launchctl start memcached

(Fedora)

% sudo chkconfig --add memcached
% sudo chkconfig --list memcached
memcached  0:off  1:off  2:off  3:on  4:on  5:on  6:off
% sudo service memcached start