Set item은 하나의 key에 대해 unique value의 집합을 저장한다. 주로 membership checking에 유용하게 사용할 수 있다.
제약 조건
저장 가능한 최대 element 개수 : 디폴트 4,000개 (attribute 설정으로 최대 50,000개 확장 가능)
각 element에서 value 최대 크기 : 16KB
Set item에 수행 가능한 기본 연산들은 다음과 같다.
여러 set element들에 대해 한번에 일괄 수행하는 연산은 다음과 같다.
Set Item 생성
새로운 empty set item을 생성한다.
memcached_return_t
memcached_sop_create(memcached_st *ptr,
const char *key, size_t key_length,
memcached_coll_create_attrs_st *attributes)
key, key_length: set item의 key
attributes: set item의 속성 정보 (링크)
Response code는 아래와 같다.
MEMCACHED_SUCCESS
MEMCACHED_CREATED: set이 생성됨.
not MEMCACHED_SUCCESS
MEMCACHED_EXISTS: 동일한 key를 가진 set이 이미 존재함.
Set item을 생성하는 예시는 아래와 같다.
int arcus_set_item_create(memcached_st *memc)
{
const char *key= "set:a_key";
uint32_t flags= 0;
uint32_t exptime= 600;
uint32_t maxcount= 1000;
memcached_return_t rc;
memcached_coll_create_attrs_st attributes;
memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
rc= memcached_sop_create(memc, key, strlen(key), &attributes);
if (memcached_failed(rc)) {
fprintf(stderr, "Failed to memcached_sop_create: %d(%s)\n", rc, memcached_strerror(memc, rc));
return -1;
}
assert(rc == MEMCACHED_SUCCESS);
assert(memcached_get_last_response_code(memc) == MEMCACHED_CREATED);
return 0;
}
Set Element 삽입
Set에 하나의 element를 삽입하는 함수이다.
memcached_return_t
memcached_sop_insert(memcached_st *ptr,
const char *key, size_t key_length,
const char *value, size_t value_length,
memcached_coll_create_attrs_st *attributes)
key, key_length: set item의 key
value, value_lenth: 삽입할 element의 value
attributes: Set 없을 시에 attributes에 따라 empty set을 생성 후에 element 삽입한다.
Response code는 아래와 같다.
MEMCACHED_SUCCESS
MEMCACHED_STORED: element만 삽입
MEMCACHED_CREATED_STORED: Set 생성 후에 element 삽입
not MEMCACHED_SUCCESS
MEMCACHED_NOTFOUND: Set이 존재하지 않음.
MEMCACHED_TYPE_MISMATCH: 주어진 key의 자료구조가 set이 아님.
MEMCACHED_OVERFLOWED: Overflow 상태임. (overflowaction=error, maxcount=count)
MEMCACHED_ELEMENT_EXISTS: 동일한 value를 가진 element가 이미 존재하고 있음
Set에 하나의 element를 삽입하는 예시는 아래와 같다.
int arcus_set_element_insert(memcached_st *memc)
{
const char *key= "set:a_key";
const char *value= "value";
memcached_return_t rc;
uint32_t flags= 0;
uint32_t exptime= 600;
uint32_t maxcount= 1000;
memcached_coll_create_attrs_st attributes;
memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
rc= memcached_sop_insert(memc, key, strlen(key), value, strlen(value), &attributes);
if (memcached_failed(rc)) {
fprintf(stderr, "Failed to memcached_sop_insert: %d(%s)\n", rc, memcached_strerror(memc, rc));
return -1;
}
memcached_return_t last_response= memcached_get_last_response_code(memc);
assert(rc == MEMCACHED_SUCCESS);
assert(last_response == MEMCACHED_STORED || last_response == MEMCACHED_CREATED_STORED);
return 0;
}
Set Element 삭제
Set에서 주어진 value를 가진 element를 삭제하는 함수이다.
memcached_return_t
memcached_sop_delete(memcached_st *ptr,
const char *key, size_t key_length,
const char *value, size_t value_length,
bool drop_if_empty)
key, key_length: set item의 key
value, value_length: 삭제할 element의 value
drop_if_empty: element 삭제로 empty list가 될 경우, 그 list도 삭제할 것인지를 지정
Response code는 아래와 같다.
MEMCACHED_SUCCESS
MEMCACHED_DELETED: 주어진 value를 가지는 element를 삭제함.
MEMCACHED_DELETED_DROPPED: 주어진 value를 가지는 element를 삭제하고, empty 상태가 된 Set도 삭제함.
not MEMCACHED_SUCCESS
MEMCACHED_NOTFOUND: 주어진 key에 해당하는 Set이 없음.
MEMCACHED_NOTFOUND_ELEMENT: 주어진 value를 가지는 element가 없음.
MEMCACHED_TYPE_MISMATCH: 주어진 key에 해당하는 자료구조가 Set이 아님.
Set에서 하나의 element를 삭제하는 예시는 아래와 같다.
int arcus_set_element_delete(memcached_st *memc)
{
const char *key= "set:a_key";
const char *value= "value";
bool drop_if_empty= false;
memcached_return_t rc;
rc= memcached_sop_delete(memc, key, strlen(key), value, strlen(value), drop_if_empty);
if (memcached_failed(rc)) {
fprintf(stderr, "Failed to memcached_sop_delete: %d(%s)\n", rc, memcached_strerror(memc, rc));
return -1;
}
memcached_return_t last_response= memcached_get_last_response_code(memc);
assert(rc == MEMCACHED_SUCCESS);
assert(last_response == MEMCACHED_DELETED || last_response == MEMCACHED_DELETED_DROPPED);
return 0;
}
Set Element 존재 여부 확인
Set에서 주어진 value를 가진 element의 존재 여부를 확인한다.
memcached_return_t
memcached_sop_exist(memcached_st *ptr,
const char *key, size_t key_length,
const char *value, size_t value_length)
key, key_length: set item의 key
value, value_length: 존재 여부를 확인할 element의 value
Response code는 아래와 같다.
MEMCACHED_SUCCESS
MEMCACHED_EXIST: 주어진 value를 가지는 element가 존재함.
not MEMCACHED_SUCCESS
MEMCACHED_NOT_EXIST: 주어진 value를 가지는 element가 존재하지 않음.
MEMCACHED_NOTFOUND: 주어진 key에 해당하는 Set이 없음.
MEMCACHED_TYPE_MISMATCH: 주어진 key에 해당하는 자료구조가 Set이 아님.
MEMCACHED_UNREADABLE: 주어진 key에 해당하는 Set이 unreadable 상태임.
Set element의 존재 여부를 확인하는 예시는 아래와 같다.
int arcus_set_element_exist(memcached_st *memc)
{
const char *key= "set:a_key";
const char *value= "value";
memcached_return_t rc;
rc= memcached_sop_exist(memc, key, strlen(key), value, strlen(value));
if (memcached_failed(rc)) {
if (rc == MEMCACHED_NOT_EXIST) {
return 0; /* element doesn't exist */
}
fprintf(stderr, "Failed to memcached_sop_exist: %d(%s)\n", rc, memcached_strerror(memc, rc));
return -1;
}
memcached_return_t last_response= memcached_get_last_response_code(memc);
assert(rc == MEMCACHED_SUCCESS);
assert(last_response == MEMCACHED_EXIST);
return 1; /* element exists */
}
Set Element 조회
Set element를 조회하는 함수이다. 이 함수는 임의의 count 개 elements를 조회한다.
memcached_return_t
memcached_sop_get(memcached_st *ptr,
const char *key, size_t key_length,
size_t count, bool with_delete, bool drop_if_empty,
memcached_coll_result_st *result)
key, key_length: set item의 key
count: 조회할 element 개수를 지정. 0이면 전체 elements를 의미
with_delete: 조회와 함께 삭제도 수행할 것인지를 지정
drop_if_empty: element 삭제로 empty set이 될 경우, 그 set도 삭제할 것인지를 지정
Response code는 아래와 같다.
MEMCACHED_SUCCESS
MEMCACHED_END: Set에서 정상적으로 element를 조회하였음.
MEMCACHED_DELETED: Set에서 정상적으로 element를 조회하였으며, 동시에 이들을 삭제하였음.
MEMCACHED_DELETED_DROPPED: Set에서 정상적으로 element를 조회하였으며, 동시에 이들을 삭제하였음. 이 결과 empty 상태가 된 Set을 삭제함.
not MEMCACHED_SUCCESS
MEMCACHED_NOTFOUND: 주어진 key에 해당하는 Set이 없음.
MEMCACHED_NOTFOUND_ELEMENT: 주어진 value를 가지는 element가 없음.
MEMCACHED_TYPE_MISMATCH: 주어진 key에 해당하는 자료구조가 Set이 아님.
MEMCACHED_UNREADABLE: 주어진 key에 해당하는 Set이 unreadable 상태임.
조회 결과는 memcached_coll_result_t 구조체에 저장된다. 조회 결과에 접근하기 위한 API는 다음과 같다.
memcached_coll_result_st *
memcached_coll_result_create(const memcached_st *ptr, memcached_coll_result_st *result)
void
memcached_coll_result_free(memcached_coll_result_st *result)
memcached_coll_type_t
memcached_coll_result_get_type(memcached_coll_result_st *result)
size_t
memcached_coll_result_get_count(memcached_coll_result_st *result)
uint32_t
memcached_coll_result_get_flags(memcached_coll_result_st *result)
const char *
memcached_coll_result_get_value(memcached_coll_result_st *result, size_t index)
size_t
memcached_coll_result_get_value_length(memcached_coll_result_st *result, size_t index)
memcached_coll_result_create : 새로운 result 구조체를 생성한다.
result 인자가 NULL인 경우, result 구조체를 생성 및 초기화하여 반환한다.
result 인자가 NULL이 아닌 경우, 해당 result 구조체를 초기화하여 반환한다.
memcached_coll_result_free : 동적으로 할당된 result 구조체 및 result 내부 값들의 메모리를 해제(free)한다.
memcached_coll_result_get_type : 조회한 item의 type을 가져온다.
memcached_coll_result_get_count : 조회한 item의 count를 가져온다.
memcached_coll_result_get_flags : 조회한 item의 flags를 가져온다.
memcached_coll_result_get_value : 조회한 item의 value를 가져온다.
memcached_coll_result_get_value_length : 조회한 item의 value 길이 정보를 가져온다.
Set element를 조회하는 예시는 아래와 같다.
int arcus_set_element_get(memcached_st *memc)
{
const char *key= "set:a_key";
size_t count= 0;
bool with_delete = false;
bool drop_if_empty = false;
memcached_coll_result_st result;
memcached_return_t rc;
memcached_coll_result_create(memc, &result);
do {
rc= memcached_sop_get(memc, key, strlen(key), count, with_delete, drop_if_empty, &result);
if (memcached_failed(rc)) {
fprintf(stderr, "Failed to memcached_sop_get: %d(%s)\n", rc, memcached_strerror(memc, rc));
break;
}
memcached_return_t last_response= memcached_get_last_response_code(memc);
assert(rc == MEMCACHED_SUCCESS);
assert(last_response == MEMCACHED_END ||
last_response == MEMCACHED_DELETED || last_response == MEMCACHED_DELETED_DROPPED);
for (size_t i=0; i<memcached_coll_result_get_count(&result); i++) {
const char* value= memcached_coll_result_get_value(&result, i);
fprintf(stdout, "memcached_sop_get: %s : %s\n", key, value);
}
} while(0);
memcached_coll_result_free(&result);
return (rc == MEMCACHED_SUCCESS) ? 0 : -1;
}
Set Element 일괄 삽입
Set에 여러 elements를 한번에 삽입하는 함수는 두 가지가 있다.
첫째, 하나의 key가 가리키는 set에 다수의 elements를 삽입하는 함수이다.
memcached_return_t
memcached_sop_piped_insert(memcached_st *ptr,
const char *key, const size_t key_length,
const size_t number_of_piped_items,
const char * const *values, const size_t *values_length,
memcached_coll_create_attrs_st *attributes,
memcached_return_t *results,
memcached_return_t *piped_rc)
key, key_length: 하나의 key를 지정
number_of_piped_items: 한번에 삽입할 element 개수
values, values_length: 다수 element 각각의 value와 그 길이
attributes: 해당 set이 없을 시에, attributes에 따라 set을 생성 후에 삽입한다.
하나의 key가 가리키는 set에 다수의 elements를 삽입하는 예시는 다음과 같다.
int arcus_set_element_piped_insert(memcached_st *memc)
{
const char *key= "set:a_key";
const char * const values[]= { "value1", "value2", "value3" };
size_t number_of_values = 3;
size_t values_len[3];
memcached_return_t rc;
memcached_return_t piped_rc;
memcached_return_t results[3];
uint32_t flags= 0;
uint32_t exptime= 600;
uint32_t maxcount= 1000;
memcached_coll_create_attrs_st attributes;
memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
for (size_t i=0; i<number_of_values; i++)
{
values_len[i]= strlen(values[i]);
}
rc= memcached_sop_piped_insert(memc, key, strlen(key),
number_of_values,
values, values_len,
&attributes, results, &piped_rc);
if (memcached_failed(rc)) {
fprintf(stderr, "Failed to memcached_sop_piped_insert: %d(%s)\n",
rc, memcached_strerror(memc, rc));
return -1;
}
if (piped_rc == MEMCACHED_ALL_FAILURE) {
fprintf(stderr, "Failed to memcached_sop_piped_insert: All Failures\n");
return -1;
}
if (piped_rc == MEMCACHED_SOME_SUCCESS) {
for (size_t i=0; i<number_of_values; i++) {
if (results[i] != MEMCACHED_STORED && results[i] != MEMCACHED_CREATED_STORED) {
fprintf(stderr, "Failed to memcached_sop_piped_insert: %s : %s %d(%s)\n",
key, values[i], results[i], memcached_strerror(memc, results[i]));
}
}
}
assert(rc == MEMCACHED_SUCCESS);
return 0;
}
둘째, 여러 key들이 가리키는 set들에 각각 하나의 element를 삽입하는 함수이다.
memcached_return_t
memcached_sop_piped_insert_bulk(memcached_st *ptr,
const char * const *keys,
const size_t *key_length,
const size_t number_of_keys,
const char *value, size_t value_length,
memcached_coll_create_attrs_st *attributes,
memcached_return_t *results,
memcached_return_t *piped_rc)
keys, key_length: 다수 key들을 지정
values, values_length: 각 set에 삽입할 element의 value와 그 길이
attributes: 해당 set이 없을 시에, attributes에 따라 set을 생성 후에 삽입한다.
Set element 일괄 삽입의 결과는 아래의 인자를 통해 받는다.
results: 일괄 삽입 결과가 주어진 key 또는 (key, element) 순서대로 저장된다.
CREATE_STORED: set item 생성 후에, element 삽입
piped_rc: 일괄 저장의 전체 결과를 담고 있다
MEMCACHED_ALL_SUCCESS: 모든 element가 저장됨.
MEMCACHED_SOME_SUCCESS: 일부 element가 저장됨.
MEMCACHED_ALL_FAILURE: 전체 element가 저장되지 않음.
여러 key들이 가리키는 set들에 각각 하나의 element를 삽입하는 예시는 아래와 같다.
int arcus_set_element_piped_insert_bulk(memcached_st *memc)
{
const char * const keys[]= { "set:a_key1", "set:a_key2", "set:a_key3" };
const char *value= "value";
size_t keys_len[3];
size_t number_of_keys = 3;
memcached_return_t rc;
memcached_return_t piped_rc;
memcached_return_t results[3];
uint32_t flags= 0;
uint32_t exptime= 600;
uint32_t maxcount= 1000;
memcached_coll_create_attrs_st attributes;
memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
for (size_t i=0; i<number_of_keys; i++)
{
keys_len[i]= strlen(keys[i]);
}
rc= memcached_sop_piped_insert_bulk(memc, keys, keys_len,
number_of_keys,
value, strlen(value),
&attributes, results, &piped_rc);
if (memcached_failed(rc)) {
fprintf(stderr, "Failed to memcached_sop_piped_insert: %d(%s)\n",
rc, memcached_strerror(memc, rc));
return -1;
}
if (piped_rc == MEMCACHED_ALL_FAILURE) {
fprintf(stderr, "Failed to memcached_sop_piped_insert_bulk: All Failures\n");
return -1;
}
if (piped_rc == MEMCACHED_SOME_SUCCESS) {
for (size_t i=0; i<number_of_keys; i++) {
if (results[i] != MEMCACHED_STORED && results[i] != MEMCACHED_CREATED_STORED) {
fprintf(stderr, "Failed to memcached_sop_piped_insert_bulk: %s : %s %d(%s)\n",
keys[i], value, results[i], memcached_strerror(memc, results[i]));
}
}
}
assert(rc == MEMCACHED_SUCCESS || rc == MEMCACHED_SOME_ERRORS);
return 0;
}
Set Element 일괄 존재 여부 확인
Set에서 여러 elements의 존재 여부를 한번에 확인하는 함수이다.
memcached_return_t
memcached_sop_piped_exist(memcached_st *ptr,
const char *key, size_t key_length,
const size_t number_of_piped_items,
const char * const *values, const size_t *values_length,
memcached_return_t *results,
memcached_return_t *piped_rc)
key, key_length: 하나의 key를 지정
number_of_piped_items: 한번에 확인할 element 개수
values, values_length: 각 element의 value와 길이
Set element 일괄 존재 여부 확인의 결과는 아래의 인자를 통해 받는다.
results: 각 value에 대한 element 존재 여부 결과를 순서대로 저장한다.
piped_rc: 일괄 존재 여부 확인 결과를 담고 있다.
MEMCACHED_ALL_EXIST: 모든 element가 존재함.
MEMCACHED_SOME_EXIST: 일부 element가 존재함.
MEMCACHED_ALL_NOT_EXIST: 모든 element가 존재하지 않음.
MEMCACHED_SOME_SUCCESS: 일부 element 존재 여부 확인에 실패함.
MEMCACHED_ALL_FAILURE: 전체 element 존재 여부 확인에 실패함.
Set elements의 존재 여부를 한번에 확인하는 예시는 다음과 같다.
int arcus_set_element_piped_exist(memcached_st *memc)
{
const char *key= "set:a_key";
const char * const values[]= { "value1", "value2", "value3" };
size_t number_of_values = 3;
size_t values_len[3];
memcached_return_t rc;
memcached_return_t piped_rc;
memcached_return_t results[3];
for (size_t i=0; i<number_of_values; i++)
{
values_len[i]= strlen(values[i]);
}
rc= memcached_sop_piped_exist(memc, key, strlen(key),
number_of_values,
values, values_len,
results, &piped_rc);
if (memcached_failed(rc)) {
fprintf(stderr, "Failed to memcached_sop_piped_exist: %d(%s)\n",
rc, memcached_strerror(memc, rc));
return -1;
}
if (piped_rc == MEMCACHED_ALL_FAILURE) {
fprintf(stderr, "Failed to memcached_sop_piped_exist: All Failures\n");
return -1;
}
if (piped_rc == MEMCACHED_SOME_SUCCESS) {
for (size_t i=0; i<number_of_values; i++) {
if (results[i] != MEMCACHED_EXIST && results[i] != MEMCACHED_NOT_EXIST) {
fprintf(stderr, "Failed to memcached_sop_piped_exist: %s : %s %d(%s)\n",
key, values[i], results[i], memcached_strerror(memc, results[i]));
}
}
}
assert(rc == MEMCACHED_SUCCESS);
return 0;
}
