memcache 笔记

Memcache Functions 函数参考

============================================================

简介

　　Memcache 模块提供给程序和对象方便的接口用于内存缓存，特别是用于设计动态 web 程序时减少数据库的访问，高效的一个缓存守护进程。



　　Memcache 模块也提供用于通信对话（session handler）的处理。



　　更多Memcache 模块相关信息可以到 http://www.danga.com/memcached/ 查阅。

------------------------------------------------------------

需求

　　这个模块所使用的函数包括以 zlib　进行压缩，所以 Zlib 必须安装。

　　PHP 4.3.3 或更高版本才可使用 memcache 扩展。

------------------------------------------------------------

安装

　　本 PECL（PHP 扩展公共库） 扩展未绑定于 PHP 中。 安装此 PECL 扩展库的信息可在手册中标题为 PECL 扩展库安装的一章中找到。 更多信息如新版本，下载，源文件，维护者信息以及更新日志等可以在这里找到： » http://pecl.php.net/package/memcache.



　　为了使用这些函数你必须编译 PHP 时使用 --enable-memcache[=DIR] 选项来获得 Memcache 支持。

　　你可以使用选项 --disable-memcache-session 来禁用通信对话的处理（session handler）功能。



　　Windows 用户可以在 php.ini 中增加 php_memcache.dll 扩展来使用这些相关函数。可以从 » PHP 下载页面或者 » http://snaps.php.net/ 下载此 PECL 扩展的 DLL 文件。

------------------------------------------------------------

运行时配置

　　这些函数的行为受 php.ini 的影响。



Memcache 配置项列表



名称                             默认值        是否可变           改变日志

memcache.allow_failover          "1"           PHP_INI_ALL        Available since memcache 2.0.2.

memcache.max_failover_attempts   "20"          PHP_INI_ALL        Available since memcache 2.1.0.

memcache.chunk_size              "8192"        PHP_INI_ALL        Available since memcache 2.0.2.

memcache.default_port            "11211"       PHP_INI_ALL        Available since memcache 2.0.2.

memcache.hash_strategy           "standard"    PHP_INI_ALL        Available since memcache 2.2.0.

memcache.hash_function           "crc32"       PHP_INI_ALL        Available since memcache 2.2.0.

session.save_handler             "files"       PHP_INI_ALL        Supported since memcache 2.1.2

session.save_path                ""            PHP_INI_ALL        Supported since memcache 2.1.2



　　有关 PHP_INI_* 常量进一步的细节与定义参见php.ini 配置选项。



以下是配置选项的简要解释。



memcache.allow_failover boolean

　　是否在错误时将明显的故障转移到其他服务器上处理。

　　Whether to transparently failover to other servers on errors.



memcache.max_failover_attempts integer

　　定义尝试多少个服务器来进行设置和获取数据。只用于联合 memcache.allow_failover 一同使用。

　　Defines how many servers to try when setting and getting data. Used only in conjunction with memcache.allow_failover.



memcache.chunk_size integer

　　数据将会被分成指定大小的块来传输，设置这个值越小将请求越多的网络写操作。如果提示其他无法说明的减速请将这个值设置为 32768。

　　Data will be transferred in chunks of this size, setting the value lower requires more network writes. Try increasing this value to 32768 if noticing otherwise inexplicable slowdowns.



memcache.default_port string

　　连接 memcached 服务器时如果没有指定其他端口时使用的默认的 TCP 端口号

　　The default TCP port number to use when connecting to the memcached server if no other port is specified.



memcache.hash_strategy string

　　控制在映射 key 到服务器时使用哪种策略。设置这个值一致来使一致的 hash 算法使用于服务器接受添加或者删除池中变量时将被无条件的重新映射。设置这个值以标准的结果在旧的策略被使用时。

　　Controls which strategy to use when mapping keys to servers. Set this value to consistent to enable consistent hashing which allows servers to be added or removed from the pool without causing keys to be remapped. Setting this value to standard results in the old strategy being used.



memcache.hash_function string

　　控制哪种 hsah 函数被应用于映射 key 到服务器过程中，默认值“crc32”使用 CRC32 算法，而“fnv”则表示使用 FNV-1a 算法。

　　Controls which hash function to apply when mapping keys to servers, crc32 uses the standard CRC32 hash while fnv uses FNV-1a.



session.save_handler string

　　设置这个值来确定是否使用 memcache 用于通信对话的处理（session handler）。

　　Use memcache as a session handler by setting this value to memcache.



session.save_path string

　　定义各服务器链接存储于通信对话单元时的分隔符号，例如：“tcp://host1:11211, tcp://host2:11211”。

　　Defines a comma separated of server urls to use for session storage, for example "tcp://host1:11211, tcp://host2:11211".



　　每个链接可以包含被接受于该服务器的参数，比较类似使用 Memcache::addServer() 来添加的服务器，例如：“tcp://host1:11211?persistent=1&weight=1&timeout=1&retry_interval=15”。

　　Each url may contain parameters which are applied to that server, they are the same as for the Memcache::addServer() method. For example "tcp://host1:11211?persistent=1&weight=1&timeout=1&retry_interval=15"

------------------------------------------------------------

资源类型

　　只有一种资源类型被应用于 memcache 模块，那就是对缓存服务器连接的链接标识符。

　　There is only one resource type used in memcache module - it's the link identifier for a cache server connection.

------------------------------------------------------------

预定义常量

Memcache Constants

Name                                 Description

MEMCACHE_COMPRESSED (integer)        用于调整在使用 Memcache::set(), Memcache::add() 和 Memcache::replace() 几个函数时的压缩比率。

MEMCACHE_HAVE_SESSION (integer)      如果通信对话的处理（session handler）被允许使用值为 1，其他情况值为 0。





Memcache Functions 函数列表

============================================================

bool Memcache::connect ( string $host [, int $port [, int $timeout ]] )

　　连接服务器

------------------------------------------------------------

参数

host               服务器域名或 IP

port              端口号，默认为 11211

timeout            超时连接失效的秒数，修改默认值 1 时要三思，有可能失去所有缓存方面的优势导致连接变得很慢

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);



/* OO API */

$memcache = new Memcache;

$memcache->connect('memcache_host', 11211);

?>

============================================================

bool Memcache::pconnect ( string $host [, int $port [, int $timeout ]] )

　　以常连接方式连接服务器

------------------------------------------------------------

参数

host               服务器域名或 IP

port               端口号，默认为 11211

timeout            超时连接失效的秒数，修改默认值 1 时要三思，有可能失去所有缓存方面的优势导致连接变得很慢

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_pconnect('memcache_host', 11211);



/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->pconnect('memcache_host', 11211);

?>

============================================================

bool Memcache::close ( void )

　　关闭对象

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

/*   do something here ..   */

memcache_close($memcache_obj);



/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->connect('memcache_host', 11211);

/*   do something here ..   */

$memcache_obj->close();

?>

============================================================

bool Memcache::addServer ( string $host [, int $port [, bool $persistent [, int $weight [, int $timeout [, int $retry_interval [, bool $status [, callback $failure_callback ]]]]]]] )

　　向对象添加一个服务器

------------------------------------------------------------

参数

host               服务器域名或 IP

port               端口号，默认为 11211

persistent         是否使用常连接，默认为 TRUE

weight             权重，在多个服务器设置中占的比重

timeout            超时连接失效的秒数，修改默认值 1 时要三思，有可能失去所有缓存方面的优势导致连接变得很慢

retry_interval    服务器连接失败时的重试频率，默认是 15 秒一次，如果设置为 -1 将禁止自动重试，当扩展中加载了 dynamically via dl() 时，无论本参数还是常连接设置参数都会失效。

                   每一个失败的服务器在失效前都有独自的生存期，选择后端请求时会被跳过而不服务于请求。一个过期的连接将成功的重新连接或者被标记为失败的连接等待下一次重试。这种效果就是说每一个 web server 的子进程在服务于页面时的重试连接都跟他们自己的重试频率有关。

status             控制服务器是否被标记为 online，设置这个参数为 FALSE 并设置 retry_interval 为 -1 可以使连接失败的服务器被放到一个描述不响应请求的服务器池子中，对这个服务器的请求将失败，接受设置为失败服务器的设置，默认参数为 TRUE，代表该服务器可以被定义为 online。

failure_callback   失败时的回调函数，函数的两个参数为失败服务器的 hostname 和 port

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

$memcache_obj = memcache_connect("localhost", 11211);



/* procedural API */

memcache_add($memcache_obj, 'var_key', 'test variable', FALSE, 30);



/* OO API */

$memcache_obj->add('var_key', 'test variable', FALSE, 30);

?>

============================================================

bool Memcache::add ( string $key , mixed $var [, int $flag [, int $expire ]] )

添加一个要缓存的变量

------------------------------------------------------------

参数

key                键

var                值，整型将直接存储，其他类型将被序列化存储

flag               是否使用 zlib 压缩

expire             过期时间，0 为永不过期，可使用 unix 时间戳格式或距离当前时间的秒数，设为秒数时不能大于 2592000（30 天）

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

$memcache_obj = memcache_connect("localhost", 11211);



/* procedural API */

memcache_add($memcache_obj, 'var_key', 'test variable', FALSE, 30);



/* OO API */

$memcache_obj->add('var_key', 'test variable', FALSE, 30);

?>

============================================================

bool Memcache::replace ( string $key , mixed $var [, int $flag [, int $expire ]] )

替换一个指定 key 的已存在的缓存变量内容

------------------------------------------------------------

参数

key                键

var                值，整型将直接存储，其他类型将被序列化存储

flag               是否使用 zlib 压缩

expire             过期时间，0 为永不过期，可使用 unix 时间戳格式或距离当前时间的秒数，设为秒数时不能大于 2592000（30 天）

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

$memcache_obj = memcache_connect('memcache_host', 11211);



/* procedural API */

memcache_replace($memcache_obj, "test_key", "some variable", FALSE, 30);



/* OO API */

$memcache_obj->replace("test_key", "some variable", FALSE, 30);

?>

============================================================

bool Memcache::set ( string $key , mixed $var [, int $flag [, int $expire ]] )

设置一个指定 key 的缓存变量内容

------------------------------------------------------------

参数

key                键

var                值，整型将直接存储，其他类型将被序列化存储

flag               是否使用 zlib 压缩

expire             过期时间，0 为永不过期，可使用 unix 时间戳格式或距离当前时间的秒数，设为秒数时不能大于 2592000（30 天）

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */



/* connect to memcached server */

$memcache_obj = memcache_connect('memcache_host', 11211);



/*

set value of item with key 'var_key'

using 0 as flag value, compression is not used

expire time is 30 seconds

*/

memcache_set($memcache_obj, 'var_key', 'some variable', 0, 30);



echo memcache_get($memcache_obj, 'var_key');

?>

<?php

/* OO API */

$memcache_obj = new Memcache;



/* connect to memcached server */

$memcache_obj->connect('memcache_host', 11211);



/*

set value of item with key 'var_key', using on-the-fly compression

expire time is 50 seconds

*/

$memcache_obj->set('var_key', 'some really big variable', MEMCACHE_COMPRESSED, 50);



echo $memcache_obj->get('var_key');

?>

============================================================

string Memcache::get ( string $key [, int &$flags ] )

array Memcache::get ( array $keys [, array &$flags ] )

　　获取某个 key 的变量缓存值

------------------------------------------------------------

参数

key                键

flags              如果是传址某个变量，结果将被存于该变量

------------------------------------------------------------

返回值

　　返回缓存的指定 key 的变量内容或者是在失败或该变量的值不存在时返回 FALSE

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

$var = memcache_get($memcache_obj, 'some_key');



/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->connect('memcache_host', 11211);

$var = $memcache_obj->get('some_key');



/*

You also can use array of keys as a parameter.

If such item wasn't found at the server, the result

array simply will not include such key.

*/



/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

$var = memcache_get($memcache_obj, Array('some_key', 'another_key'));



/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->connect('memcache_host', 11211);

$var = $memcache_obj->get(Array('some_key', 'second_key'));

?>

============================================================

bool Memcache::delete ( string $key [, int $timeout ] )

删除某一个变量的缓存

------------------------------------------------------------

参数

key                键

timeout            超时连接失效的秒数，修改默认值 1 时要三思，有可能失去所有缓存方面的优势导致连接变得很慢

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);



/* after 10 seconds item will be deleted by the server */

memcache_delete($memcache_obj, 'key_to_delete', 10);



/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->connect('memcache_host', 11211);



$memcache_obj->delete('key_to_delete', 10);

?>

============================================================

bool Memcache::flush ( void )

　　清空所有缓存内容，不是真的删除缓存的内容，只是使所有变量的缓存过期，使内存中的内容被重写

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);



memcache_flush($memcache_obj);



/* OO API */



$memcache_obj = new Memcache;

$memcache_obj->connect('memcache_host', 11211);



$memcache_obj->flush();

?>

============================================================

array Memcache::getExtendedStats ([ string $type [, int $slabid [, int $limit ]]] )

　　获取服务器扩展静态信息

------------------------------------------------------------

参数

type               静态信息类型，有效值包括{reset, malloc, maps, cachedump, slabs, items, sizes}，依照一定规则协议这个可选参数是为了方便开发人员查看不同类别的信息而输入的标题

slabid             用于按指定类型联合设置 cache 堆为有效的片到堆中。缓存堆被被命令绑定到服务器上并被严格的用于调试用途

limit              用于按指定类型联合设置 cache 堆为输入的数字所限制的大小到堆，默认值为 100

------------------------------------------------------------

返回值

　　返回一个由两个一定格式的数组组成的服务器扩展静态信息数组，失败时返回 FALSE

------------------------------------------------------------

范例

<?php

    $memcache_obj = new Memcache;

    $memcache_obj->addServer('memcache_host', 11211);

    $memcache_obj->addServer('failed_host', 11211);

  

    $stats = $memcache_obj->getExtendedStats();

    print_r($stats);

?>

输出结果

Array

(

    [memcache_host:11211] => Array

        (

            [pid] => 3756

            [uptime] => 603011

            [time] => 1133810435

            [version] => 1.1.12

            [rusage_user] => 0.451931

            [rusage_system] => 0.634903

            [curr_items] => 2483

            [total_items] => 3079

            [bytes] => 2718136

            [curr_connections] => 2

            [total_connections] => 807

            [connection_structures] => 13

            [cmd_get] => 9748

            [cmd_set] => 3096

            [get_hits] => 5976

            [get_misses] => 3772

            [bytes_read] => 3448968

            [bytes_written] => 2318883

            [limit_maxbytes] => 33554432

        )



    [failed_host:11211] => FALSE

)

============================================================

array Memcache::getStats ([ string $type [, int $slabid [, int $limit ]]] )

　　获取服务器静态信息

------------------------------------------------------------

参数

type               静态信息类型，有效值包括{reset, malloc, maps, cachedump, slabs, items, sizes}，依照一定规则协议这个可选参数是为了方便开发人员查看不同类别的信息而输入的标题

slabid             用于按指定类型联合设置 cache 堆为有效的片到堆中。缓存堆被被命令绑定到服务器上并被严格的用于调试用途

limit              用于按指定类型联合设置 cache 堆为输入的数字所限制的大小到堆，默认值为 100

------------------------------------------------------------

返回值

　　返回一个由两个一定格式的数组组成的服务器静态信息数组，失败时返回 FALSE

============================================================

int Memcache::getServerStatus ( string $host [, int $port ] )

　　通过输入的 host 及 port 来获取相应的服务器信息

------------------------------------------------------------

参数

host               服务器域名或 IP

port               端口号，默认为 11211

------------------------------------------------------------

返回值

　　返回服务器状态，0 为失败，其他情况返回非 0 数字

------------------------------------------------------------

范例

<?php

/* OO API */

$memcache = new Memcache;

$memcache->addServer('memcache_host', 11211);

echo $memcache->getServerStatus('memcache_host', 11211);



/* procedural API */

$memcache = memcache_connect('memcache_host', 11211);

echo memcache_get_server_status($memcache, 'memcache_host', 11211);

?>

============================================================

string Memcache::getVersion ( void )

　　获取服务器的版本号信息

------------------------------------------------------------

返回值

　　成功返回服务器的版本号字符串，失败返回 FALSE

------------------------------------------------------------

范例

<?php

/* OO API */

$memcache = new Memcache;

$memcache->connect('memcache_host', 11211);

echo $memcache->getVersion();



/* procedural API */

$memcache = memcache_connect('memcache_host', 11211);

echo memcache_get_version($memcache);

?>

============================================================

bool Memcache::setCompressThreshold ( int $threshold [, float $min_savings ] )

　　设置压缩极限

------------------------------------------------------------

参数

threshold           设置控制自动压缩的变量长度的最小值

min_saving         指定的最低压缩比率，值必须介于 0 - 1 之间，默认为 0.2 代表 20% 的压缩比率

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->addServer('memcache_host', 11211);

$memcache_obj->setCompressThreshold(20000, 0.2);



/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

memcache_set_compress_threshold($memcache_obj, 20000, 0.2);

?>

============================================================

bool Memcache::setServerParams ( string $host [, int $port [, int $timeout [, int $retry_interval [, bool $status [, callback $failure_callback ]]]]] )

Memcache version 2.1.0 后增加的函数，运行时设置服务器参数

------------------------------------------------------------

参数

host               服务器域名或 IP

port               端口号，默认为 11211

timeout            超时连接失效的秒数，修改默认值 1 时要三思，有可能失去所有缓存方面的优势导致连接变得很慢

retry_interval    服务器连接失败时的重试频率，默认是 15 秒一次，如果设置为 -1 将禁止自动重试，当扩展中加载了 dynamically via dl() 时，无论本参数还是常连接设置参数都会失效。

                   每一个失败的服务器在失效前都有独自的生存期，选择后端请求时会被跳过而不服务于请求。一个过期的连接将成功的重新连接或者被标记为失败的连接等待下一次重试。这种效果就是说每一个 web server 的子进程在服务于页面时的重试连接都跟他们自己的重试频率有关。

status             控制服务器是否被标记为 online，设置这个参数为 FALSE 并设置 retry_interval 为 -1 可以使连接失败的服务器被放到一个描述不响应请求的服务器池子中，对这个服务器的请求将失败，接受设置为失败服务器的设置，默认参数为 TRUE，代表该服务器可以被定义为 online。

failure_callback   失败时的回调函数，函数的两个参数为失败服务器的 hostname 和 port

------------------------------------------------------------

返回值

　　成功返回 TRUE，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

function _callback_memcache_failure($host, $port) {

    print "memcache '$host:$port' failed";

}



/* OO API */

$memcache = new Memcache;



// Add the server in offline mode

$memcache->addServer('memcache_host', 11211, FALSE, 1, 1, -1, FALSE);



// Bring the server back online

$memcache->setServerParams('memcache_host', 11211, 1, 15, TRUE, '_callback_memcache_failure');



/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

memcache_set_server_params($memcache_obj, 'memcache_host', 11211, 1, 15, TRUE, '_callback_memcache_failure');

?>

============================================================

int Memcache::increment ( string $key [, int $value ] )

　　给指定 key 的缓存变量一个增值，如果该变量不是数字时不会被转化为数字，这个增值将会加到该变量原有的数字之上，变量不存在不会新增变量，对于压缩存储的变量不要使用本函数因为相应的取值方法会失败。

------------------------------------------------------------

参数

key                键

var                值，整型将直接存储，其他类型将被序列化存储

------------------------------------------------------------

返回值

　　成功返回新的变量值，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

/* increment counter by 2 */

$current_value = memcache_increment($memcache_obj, 'counter', 2);



/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->connect('memcache_host', 11211);

/* increment counter by 3 */

$current_value = $memcache_obj->increment('counter', 3);

?>

============================================================

int Memcache::decrement ( string $key [, int $value ] )

　　给指定 key 的缓存变量一个递减值，与 increment 操作类似，将在原有变量基础上减去这个值，该项的值将会在转化为数字后减去，新项的值不会小于 0，对于压缩存储的变量不要使用本函数因为相应的取值方法会失败。

------------------------------------------------------------

参数

key                键

var                值，整型将直接存储，其他类型将被序列化存储

------------------------------------------------------------

返回值

　　成功返回新的变量值，失败返回 FALSE。

------------------------------------------------------------

范例

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

/* decrement item by 2 */

$new_value = memcache_decrement($memcache_obj, 'test_item', 2);



/* OO API */

$memcache_obj = new Memcache;

$memcache_obj->connect('memcache_host', 11211);

/* decrement item by 3 */

$new_value = $memcache_obj->decrement('test_item', 3);

?>

============================================================

bool memcache_debug ( bool $on_off )

　　设置 memcache 的调试器是否开启，值为 TRUE 或 FALSE。

　　受影响于 php 安装时是否使用了 --enable-debug 选项，如果使用了该函数才会返回 TRUE，其他情况将始终返回 FALSE。

------------------------------------------------------------

参数

on_off             设置调试模式是否开启，TRUE 为开启，FALSE 为关闭

------------------------------------------------------------

返回值

　　php 安装时如果使使用了 --enable-debug 选项返回 TRUE，否则将返回 FALSE。