List Item

List item은 하나의 key에 대해 여러 value들을 double linked list 구조로 유지한다.

제약 조건

• 저장 가능한 최대 element 개수: 디폴트 4,000개 (attribute 설정으로 최대 50,000개 확장 가능)

• 각 element에서 value 최대 크기 : 16KB

• List의 앞, 뒤에서 element를 삽입/삭제하기를 권한다. 임의의 index 위치에서 element 삽입/삭제가 가능하지만, 임의의 index 위치를 신속히 찾아가기 위한 자료구조가 현재 없는 상태라서 비용이 많이 든다.

List item에 대해 수행 가능한 기본 연산들은 아래와 같다.

• List Item 생성 (List Item 삭제는 key-value item 삭제 함수로 수행한다)

• List Element 삽입

• List Element 삭제

• List Element 조회

여러 list element들에 대해 한번에 일괄 수행하는 연산은 다음과 같다.

• List Element 일괄 삽입

List Item 생성

새로운 empty list item을 생성한다.

memcached_return_t
memcached_lop_create(memcached_st *ptr,
                     const char *key, size_t key_length,
                     memcached_coll_create_attrs_st *attributes)

• key, key_length: list item의 key

• attributes: list item의 속성 정보 (링크)

Response code는 아래와 같다.

• MEMCACHED_SUCCESS

  • MEMCACHED_CREATED: List가 생성됨.

• not MEMCACHED_SUCCESS

  • MEMCACHED_EXISTS: 동일한 key를 가진 List가 이미 존재함.

List item을 생성하는 예시는 아래와 같다.

int arcus_list_item_create(memcached_st *memc)
{
  const char *key= "list: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_lop_create(memc, key, strlen(key), &attributes);
  if (memcached_failed(rc)) {
    fprintf(stderr, "Failed to memcached_lop_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;
}

List Element 삽입

List에 하나의 element를 삽입하는 함수이다.

memcached_return_t
memcached_lop_insert(memcached_st *ptr,
                     const char *key, size_t key_length,
                     const int32_t index,
                     const char *value, size_t value_length,
                     memcached_coll_create_attrs_st *attributes)

• key, key_length: list item의 key

• index: list index (0-based index)

  • 0, 1, 2, ... : list의 앞에서 시작하여 각 element 위치를 나타냄

  • -1, -2, -3, ... : list의 뒤에서 시작하여 각 element 위치를 나타냄

• value, value_length: 삽입할 element의 value

• attributes: List 없을 시에 attributes에 따라 empty list를 생성 후에 element 삽입한다.

Response code는 아래와 같다.

• MEMCACHED_SUCCESS

  • MEMCACHED_STORED: 기존에 존재하던 List에 element가 삽입됨.

  • MEMCACHED_CREATED_STORED: List가 새롭게 생성되고 element가 삽입됨.

• not MEMCACHED_SUCCESS

  • MEMCACHED_NOTFOUND: List가 존재하지 않음.

  • MEMCACHED_TYPE_MISMATCH: 주어진 key에 해당하는 자료구조가 List가 아님.

  • MEMCACHED_OVERFLOWED: Overflow 상태임. (overflowaction=error, maxcount=count)

  • MEMCACHED_OUT_OF_RANGE: 삽입 위치가 List의 element index 범위를 넘어섬.

List element를 삽입하는 예시는 아래와 같다.

int arcus_list_element_insert(memcached_st *memc)
{
  const char *key= "list:a_key";
  const char *value= "value";
  const int32_t index= -1;
  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_lop_insert(memc, key, strlen(key),
                           index, value, strlen(value), &attributes);
  if (memcached_failed(rc)) {
    fprintf(stderr, "Failed to memcached_lop_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;
}

List Element 삭제

List element를 삭제하는 함수는 두 가지가 있다.

첫째, 하나의 list index로 하나의 element만 삭제하는 함수이다.

memcached_return_t
memcached_lop_delete(memcached_st *ptr,
                     const char *key, size_t key_length,
                     const int32_t index, bool drop_if_empty)

• index: single list index (0-based index)

  • 0, 1, 2, ... : list의 앞에서 시작하여 각 element 위치를 나타냄

  • -1, -2, -3, ... : list의 뒤에서 시작하여 각 element 위치를 나타냄

• drop_if_empty: element 삭제로 empty list가 될 경우, 그 list도 삭제할 것인지를 지정

둘째, list index range로 다수의 elements를 삭제하는 함수이다.

memcached_return_t
memcached_lop_delete_by_range(memcached_st *ptr,
                              const char *key, size_t key_length,
                              const int32_t from, const int32_t to,
                              bool drop_if_empty)

• key, key_length: list item의 key

• from, to: list index range (0-based index)

  • 0, 1, 2, ... : list의 앞에서 시작하여 각 element 위치를 나타냄

  • -1, -2, -3, ... : list의 뒤에서 시작하여 각 element 위치를 나타냄

• drop_if_empty: element 삭제로 empty list가 될 경우, 그 list도 삭제할 것인지를 지정

Response code는 아래와 같다.

• MEMCACHED_SUCCESS

  • MEMCACHED_DELETED: 주어진 index에 해당하는 element를 삭제함.

  • MEMCACHED_DELETED_DROPPED: 주어진 index에 해당하는 element를 삭제하고, empty 상태가 된 List도 삭제함.

• not MEMCACHED_SUCCESS

  • MEMCACHED_NOTFOUND: 주어진 key에 해당하는 List가 없음.

  • MEMCACHED_NOTFOUND_ELEMENT: 주어진 index나 index 범위에 해당하는 element가 없음.

  • MEMCACHED_TYPE_MISMATCH: 주어진 key에 해당하는 자료구조가 List가 아님.

List element를 삭제하는 예시는 아래와 같다.

int arcus_list_element_delete(memcached_st *memc)
{
  const char *key="list:a_key";
  const int32_t index= 0;
  // const int32_t from= 0, to= -1;
  bool drop_if_empty = false;
  memcached_return_t rc;

  rc= memcached_lop_delete(memc, key, strlen(key), index, drop_if_empty);
  /* rc= memcached_lop_delete_by_range(memc, key, strlen(key),
                                       from, to, drop_if_empty); */
  if (memcached_failed(rc)) {
    fprintf(stderr, "Failed to memcached_lop_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;
}

List Element 조회

List element를 조회하는 함수는 두 가지가 있다.

첫째, 하나의 list index로 하나의 element만 조회하는 함수이다.

memcached_return_t
memcached_lop_get(memcached_st *ptr,
                  const char *key, size_t key_length,
                  const int32_t index,
                  bool with_delete, bool drop_if_empty,
                  memcached_coll_result_st *result)

• key, key_length: list item의 key

• index: single list index (0-based index)

  • 0, 1, 2, ... : list의 앞에서 시작하여 각 element 위치를 나타냄

  • -1, -2, -3, ... : list의 뒤에서 시작하여 각 element 위치를 나타냄

• with_delete: 조회와 함께 삭제도 수행할 것인지를 지정

• drop_if_empty: element 삭제로 empty list가 될 경우, 그 list도 삭제할 것인지를 지정

둘째, list index range로 다수의 elements를 조회하는 함수이다.

memcached_return_t
memcached_lop_get_by_range(memcached_st *ptr,
                           const char *key, size_t key_length,
                           const int32_t from, const int32_t to,
                           bool with_delete, bool drop_if_empty,
                           memcached_coll_result_st *result)

• from, to: list index range (0-based index)

  • 0, 1, 2, ... : list의 앞에서 시작하여 각 element 위치를 나타냄

  • -1, -2, -3, ... : list의 뒤에서 시작하여 각 element 위치를 나타냄

• with_delete: 조회와 함께 삭제도 수행할 것인지를 지정

• drop_if_empty: element 삭제로 empty list가 될 경우, 그 list도 삭제할 것인지를 지정

Response code는 아래와 같다.

• MEMCACHED_SUCCESS

  • MEMCACHED_END: List에서 정상적으로 element를 조회하였음.

  • MEMCACHED_DELETED: List에서 정상적으로 element를 조회하였으며, 동시에 이들을 삭제하였음.

  • MEMCACHED_DELETED_DROPPED: List에서 정상적으로 element를 조회하였으며, 동시에 이들을 삭제하였음. 이 결과 empty 상태가 된 List를 삭제함.

• not MEMCACHED_SUCCESS

  • MEMCACHED_NOTFOUND: 주어진 key에 해당하는 List가 없음.

  • MEMCACHED_NOTFOUND_ELEMENT: 주어진 index 또는 index 범위에 해당하는 element가 없음.

  • MEMCACHED_TYPE_MISMATCH: 주어진 key에 해당하는 자료구조가 List가 아님.

  • MEMCACHED_UNREADABLE: 주어진 key에 해당하는 List가 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 길이 정보를 가져온다.

List element를 조회하는 예시는 아래와 같다.

int arcus_list_element_get(memcached_st *memc)
{
  const char *key= "list:a_key";
  const int32_t index= 0;
  // const int32_t from= 0, to= -1;
  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_lop_get(memc, key, strlen(key),
                          index, with_delete, drop_if_empty, &result);
    /* rc= memcached_lop_get_by_range(memc, key, strlen(key), from, to,
                                      with_delete, drop_if_empty, &result); */
    if (memcached_failed(rc)) {
      fprintf(stderr, "Failed to memcached_lop_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);

    const char* value= memcached_coll_result_get_value(&result, 0);
    fprintf(stdout, "memcached_lop_get: %s[%d] : %s\n", key, index, value);
    /* 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_lop_get: %s[%d] : %s\n", key, i, value);
    } */
  } while(0);

  memcached_coll_result_free(&result);
  return (rc == MEMCACHED_SUCCESS) ? 0 : -1;
}

List Element 일괄 삽입

List에 여러 elements를 한번에 삽입하는 함수는 두 가지가 있다.

첫째, 하나의 key가 가리키는 list에 다수의 elements를 삽입하는 함수이다.

memcached_return_t
memcached_lop_piped_insert(memcached_st *ptr,
                           const char *key, const size_t key_length,
                           const size_t number_of_piped_items,
                           const int32_t *indexes,
                           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 개수

• indexes: list index array (0-based index)

• values, values_length: 다수 element 각각의 value와 그 길이

• attributes: 해당 list가 없을 시에, attributes에 따라 list를 생성 후에 삽입한다.

하나의 key가 가리키는 list에 다수의 elements를 삽입하는 예시는 다음과 같다.

int arcus_list_element_piped_insert(memcached_st *memc)
{
  const char *key= "list:a_key";
  const char * const values[]= { "value1", "value2", "value3" };
  size_t number_of_values = 3;
  size_t values_len[3];
  int32_t indexes[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++)
  {
    indexes[i]= i;
    values_len[i]= strlen(values[i]);
  }

  rc= memcached_lop_piped_insert(memc, key, strlen(key),
                                 number_of_values, indexes,
                                 values, values_len,
                                 &attributes, results, &piped_rc);
  if (memcached_failed(rc)) {
    fprintf(stderr, "Failed to memcached_lop_piped_insert: %d(%s)\n",
            rc, memcached_strerror(memc, rc));
    return -1;
  }

  if (piped_rc == MEMCACHED_ALL_FAILURE) {
    fprintf(stderr, "Failed to memcached_lop_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_lop_piped_insert: %s[%d] %d(%s)\n",
                key, indexes[i], results[i], memcached_strerror(memc, results[i]));
      }
    }
  }

  assert(rc == MEMCACHED_SUCCESS);
  return 0;
}

둘째, 여러 key들이 가리키는 list들에 각각 하나의 element를 삽입하는 함수이다.

memcached_return_t
memcached_lop_piped_insert_bulk(memcached_st *ptr,
                                const char * const *keys, const size_t *key_length,
                                const size_t number_of_keys,
                                const int32_t index,
                                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들을 지정

• number_of_keys: key들의 수

• index: list index (0-based index)

• value, value_length: 각 list에 삽입할 element의 value와 그 길이

• attributes: 해당 list가 없을 시에, attributes에 따라 list를 생성 후에 삽입한다.

List element 일괄 삽입의 결과는 아래의 인자를 통해 받는다.

• results: 일괄 삽입 결과가 주어진 key 또는 (key, element) 순서대로 저장된다.

  • STORED: element만 삽입

  • CREATE_STORED: list item 생성 후에, element 삽입

• piped_rc: 일괄 저장의 전체 결과를 담고 있다

  • MEMCACHED_ALL_SUCCESS: 모든 element가 저장됨.

  • MEMCACHED_SOME_SUCCESS: 일부 element가 저장됨.

  • MEMCACHED_ALL_FAILURE: 전체 element가 저장되지 않음.

여러 key들이 가리키는 list들에 각각 하나의 element를 삽입하는 예시는 아래와 같다.

int arcus_list_element_piped_insert_bulk(memcached_st *memc)
{
  const char * const keys[]= { "list:a_key1", "list:a_key2", "list:a_key3" };
  const char *value= "value";
  size_t keys_len[3];
  size_t number_of_keys = 3;
  int32_t index= -1;
  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_lop_piped_insert_bulk(memc, keys, keys_len,
                                      number_of_keys, index,
                                      value, strlen(value),
                                      &attributes, results, &piped_rc);
  if (memcached_failed(rc)) {
    fprintf(stderr, "Failed to memcached_lop_piped_insert: %d(%s)\n",
            rc, memcached_strerror(memc, rc));
    return -1;
  }

  if (piped_rc == MEMCACHED_ALL_FAILURE) {
    fprintf(stderr, "Failed to memcached_lop_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_lop_piped_insert_bulk: %s[%d] %d(%s)\n",
                keys[i], index, results[i], memcached_strerror(memc, results[i]));
      }
    }
  }

  assert(rc == MEMCACHED_SUCCESS || rc == MEMCACHED_SOME_ERRORS);
  return 0;
}