diff options
Diffstat (limited to 'web/server/h2o/libh2o/deps/libyrmcds/USAGE.md')
| -rw-r--r-- | web/server/h2o/libh2o/deps/libyrmcds/USAGE.md | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/web/server/h2o/libh2o/deps/libyrmcds/USAGE.md b/web/server/h2o/libh2o/deps/libyrmcds/USAGE.md deleted file mode 100644 index 408711937..000000000 --- a/web/server/h2o/libh2o/deps/libyrmcds/USAGE.md +++ /dev/null @@ -1,221 +0,0 @@ -Usage -===== - -`yc` ----- - -`yc` is a memcached/yrmcds client program. It provides access to all -libyrmcds library functions therefore access to all server functions. - -`yc` prints out its usage when invoked without command-line arguments. - -Minimal example ---------------- - -```c -#include <yrmcds.h> - -#include <errno.h> -#include <error.h> -#include <stdlib.h> -#include <stdio.h> - -void check_error(yrmcds_error e) { - if( e != 0 ) { - if( e == YRMCDS_SYSTEM_ERROR ) { - error(0, errno, "system error"); - } else { - fprintf(stderr, "yrmcds error: %s\n", yrmcds_strerror(e)); - } - exit(2); - } -} - -void check_response(const yrmcds_response* r) { - if( r->status != YRMCDS_STATUS_OK ) { - fprintf(stderr, "Command failed: 0x%04x %.*s\n", - r->status, (int)r->data_len, r->data); - exit(3); - } -} - -int main(int argc, char** argv) { - yrmcds c; - yrmcds_response r; - - check_error( yrmcds_connect(&c, "localhost", 11211) ); - check_error( yrmcds_noop(&c, NULL) ); - check_error( yrmcds_recv(&c, &r) ); - check_response(&r); - check_error( yrmcds_close(&c) ); - - return 0; -} -``` - -Compilation and linking ------------------------ - -Link with `-lyrmcds -lpthread` as follows: - -``` -gcc -g -O2 -o foo foo.c -lyrmcds -lpthread -``` - -Request serial number ---------------------- - -All command sending functions can issue a unique serial number of the -command. This can be used when you receive responses asynchronously -as described in the next section. - -```c -uint32_t async_cas(yrmcds* c) { - uint32_t serial; - // try compare-and-swap - check_error( yrmcds_set(&c, "abc", 3, "12345", 5, 0, 0, 5, 0, &serial) ); - return serial; -} -``` - -Multi-threading ---------------- - -All functions in libyrmcds are thread-safe as long as different `yrmcds` -structs are used. Additionally, any number of threads can use command -sending functions such as `yrmcds_get()` or `yrmcds_set()` even when -they share the same `yrmcds` struct. - -Further, `yrmcds_recv()` can be used in parallel with command sending -functions. You can create a dedicated thread to receive server responses -asynchronously. Use request serial numbers to identify a response's -request. - -```c -void async_recv(yrmcds* c, void (*notify)(uint32_t, yrmcds_response* r)) { - yrmcds_respone r; - while( 1 ) { - check_error( yrmcds_recv(&c, &r) ); - (*notify)(r.serial, &r); - } -} -``` - -You can use `yrmcds_shutdown()` to interrupt the thread blocking in -`yrmcds_recv()` for graceful exit. - - -Transparent compression ------------------------ - -libyrmcds provides optional transparent data compression by [LZ4][]. - -To use this feature, the library must be built with LZ4 as follows: - -``` -$ make lz4 -$ make -``` - -If the library supports LZ4 compression, you can enable transparent -LZ4 (de)compression for large objects. The threshold for compression -can be set by `yrmcds_set_compression()`. The compression is disabled -by default. - -Note that all clients must support and enable the compression to -properly handle compressed data. - -Text protocol support ---------------------- - -Although libyrmcds is designed for binary protocol, yet it provides -limited access to text protocol commands. Use `yrmcds_text_mode()` -to put the connection into the text protocol mode: - -```c - check_error( yrmcds_connect(&c, "localhost", 11211) ); - check_error( yrmcds_text_mode(&c) ); - - // Use the library API just in the same way as binary protocol. -``` - -Limitations: - -* Only subset of commands can be used. - - `yrmcds_get_touch`, lock related functions, `yrmcds_incr2` and - `yrmcds_decr2`, stat functions, key dump extension are not supported. - -* Quiet mutation cannot be used. - - `quiet` arguments must be 0. You need to receive a response for - every command. - -* `yrmcds_response::cas_unique` is always 0 for storage commands. - - The response for `yrmcds_set`, `yrmcds_add`, or `yrmcds_replace` - will not bring the correct CAS value. Use `yrmcds_get` or - `yrmcds_getk` to retrieve the correct value. - -* `yrmcds_response::command` value is dummy. - - Because `command` is one of binary protocol command numbers. - -Counter extension ------------------ - -yrmcds has a distributed counter extension for resource management. -If the extension is enabled in server, you can access counters by `yrmcds_cnt_*` functions. -The usage of each function is very similar to the corresponding `yrmcds_` function. - -The minimum example is: - -```c -#include <yrmcds.h> - -#include <errno.h> -#include <error.h> -#include <stdio.h> -#include <stdlib.h> - -void check_error(yrmcds_error e) { - if( e != YRMCDS_OK ) { - if( e == YRMCDS_SYSTEM_ERROR ) { - error(0, errno, "system error"); - } else { - fprintf(stderr, "yrmcds error: %s\n", yrmcds_strerror(e)); - } - exit(2); - } -} - -void check_response(const yrmcds_cnt_response* r) { - if( r->status != YRMCDS_STATUS_OK ) { - fprintf(stderr, "Command failed: 0x%02x %.*s\n", - r->status, (int)r->body_length, r->body); - exit(3); - } -} - -int main(void) { - yrmcds_cnt c; - yrmcds_cnt_response r; - - check_error( yrmcds_cnt_connect(&c, "localhost", 11215) ); - check_error( yrmcds_cnt_noop(&c, NULL) ); - check_error( yrmcds_cnt_recv(&c, &r) ); - check_response(&r); - check_error( yrmcds_cnt_close(&c) ); - - return 0; -} -``` - -API documents -------------- - -HTML documents generated with Doxygen is available [here][api]. - - -[api]: http://cybozu.github.io/libyrmcds/html/ -[LZ4]: https://code.google.com/p/lz4/ |