From e6e3a97b4702d777f2e7a62fb2b42d2d6ddd5975 Mon Sep 17 00:00:00 2001
From: yeoncheol-kim <koo05131@yahoo.co.kr>
Date: Tue, 26 Nov 2024 11:47:53 +0900
Subject: [PATCH] DOC: Modify examples for the list document

---
 docs/04-list-API.md | 413 ++++++++++++++++++++++++--------------------
 1 file changed, 224 insertions(+), 189 deletions(-)

diff --git a/docs/04-list-API.md b/docs/04-list-API.md
index df04e78a..60abb830 100644
--- a/docs/04-list-API.md
+++ b/docs/04-list-API.md
@@ -22,10 +22,9 @@ List item에 대해 수행 가능한 기본 연산들은 아래와 같다.
 
 ## List Item 생성
 
-
 새로운 empty list item을 생성한다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_create(memcached_st *ptr,
                      const char *key, size_t key_length,
@@ -42,31 +41,29 @@ Response code는 아래와 같다.
 - not MEMCACHED_SUCCESS
   - MEMCACHED_EXISTS: 동일한 key를 가진 List가 이미 존재함.
 
-List item을 생성하는 예제는 아래와 같다.
+List item을 생성하는 예시는 아래와 같다.
 
-``` c
-void arcus_list_item_create(memcached_st *memc)
+```c
+int arcus_list_item_create(memcached_st *memc)
 {
-    memcached_return_t rc;
-
-    uint32_t flags= 10;
-    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_create(memc, "list:an_empty_list", strlen("list:an_empty_list"),
-                             &attributes);
-    assert(MEMCACHED_SUCCESS == rc);
-    assert(MEMCACHED_CREATED == memcached_get_last_response_code(memc));
-
-    // 리스트가 이미 존재한다면 실패한다.
-    rc= memcached_lop_create(memc, "list:an_empty_list", strlen("list:an_empty_list"),
-                             &attributes);
-    assert(MEMCACHED_SUCCESS != rc);
-    assert(MEMCACHED_EXISTS == memcached_get_last_response_code(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;
 }
 ```
 
@@ -75,7 +72,7 @@ void arcus_list_item_create(memcached_st *memc)
 
 List에 하나의 element를 삽입하는 함수이다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_insert(memcached_st *ptr,
                      const char *key, size_t key_length,
@@ -102,42 +99,33 @@ Response code는 아래와 같다.
   - MEMCACHED_OVERFLOWED: Overflow 상태임. (overflowaction=error, maxcount=count)
   - MEMCACHED_OUT_OF_RANGE: 삽입 위치가 List의 element index 범위를 넘어섬.
 
-List element를 삽입하는 예제는 아래와 같다.
+List element를 삽입하는 예시는 아래와 같다.
 
-``` c
-void arcus_list_element_insert(memcached_st *memc)
+```c
+int arcus_list_element_insert(memcached_st *memc)
 {
-    memcached_return_t rc;
-
-    uint32_t flags= 10;
-    uint32_t exptime= 600;
-    uint32_t maxcount= 1000;
-
-    memcached_coll_create_attrs_st attributes;
-    memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
-
-    int index= 0;
-
-    // 1. CREATED_STORED
-    index= 0;
-    rc= memcached_lop_insert(memc, "a_list", strlen("a_list"), index,
-                             "value", strlen("value"), &attributes);
-    assert(MEMCACHED_SUCCESS == rc);
-    assert(MEMCACHED_CREATED_STORED == memcached_get_last_response_code(memc));
-
-    // 2. STORED
-    index= 1;
-    rc= memcached_lop_insert(memc, "a_list", strlen("a_list"), index,
-                             "value", strlen("value"), &attributes);
-    assert(MEMCACHED_SUCCESS == rc);
-    assert(MEMCACHED_STORED == memcached_get_last_response_code(memc));
-
-    // 3. OUT_OF_RANGE
-    index= 10;
-    rc= memcached_lop_insert(memc, "a_list", strlen("a_list"), index,
-                             "value", strlen("value"), &attributes);
-    assert(MEMCACHED_SUCCESS != rc);
-    assert(MEMCACHED_OUT_OF_RANGE == rc);
+  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;
 }
 ```
 
@@ -147,7 +135,7 @@ List element를 삭제하는 함수는 두 가지가 있다.
 
 첫째, 하나의 list index로 하나의 element만 삭제하는 함수이다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_delete(memcached_st *ptr,
                      const char *key, size_t key_length,
@@ -161,7 +149,7 @@ memcached_lop_delete(memcached_st *ptr,
 
 둘째, list index range로 다수의 elements를 삭제하는 함수이다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_delete_by_range(memcached_st *ptr,
                               const char *key, size_t key_length,
@@ -185,38 +173,29 @@ Response code는 아래와 같다.
   - MEMCACHED_TYPE_MISMATCH: 주어진 key에 해당하는 자료구조가 List가 아님.
 
 
-List element를 삭제하는 예제는 아래와 같다.
+List element를 삭제하는 예시는 아래와 같다.
 
-``` c
-void arcus_list_element_delete(memcached_st *memc)
+```c
+int arcus_list_element_delete(memcached_st *memc)
 {
-    uint32_t flags= 10;
-    uint32_t exptime= 600;
-    uint32_t maxcount= 1000;
-
-    memcached_coll_create_attrs_st attributes;
-    memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
-
-    memcached_return_t rc;
-
-    // 테스트 데이터를 삽입한다.
-    rc= memcached_lop_insert(memc, "list:a_list", strlen("list:a_list"), -1,
-                             "value", strlen("value"), &attributes);
-    assert(MEMCACHED_SUCCESS == rc);
-
-    rc= memcached_lop_insert(memc, "list:a_list", strlen("list:a_list"), -1,
-                             "value", strlen("value"), &attributes);
-    assert(MEMCACHED_SUCCESS == rc);
-
-    // 1번 인덱스의 element를 삭제한다.
-    rc= memcached_lop_delete(memc, "list:a_list", strlen("list:a_list"), 1, true);
-    assert(MEMCACHED_SUCCESS == rc);
-    assert(MEMCACHED_DELETED == memcached_get_last_response_code(memc));
-
-    // 0번 인덱스의 element를 삭제하고, empty 상태가 된 리스트를 삭제한다.
-    rc= memcached_lop_delete(memc, "list:a_list", strlen("list:a_list"), 0, true);
-    assert(MEMCACHED_SUCCESS == rc);
-    assert(MEMCACHED_DELETED_DROPPED == memcached_get_last_response_code(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;
 }
 ```
 
@@ -226,7 +205,7 @@ List element를 조회하는 함수는 두 가지가 있다.
 
 첫째, 하나의 list index로 하나의 element만 조회하는 함수이다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_get(memcached_st *ptr,
                   const char *key, size_t key_length,
@@ -244,7 +223,7 @@ memcached_lop_get(memcached_st *ptr,
 
 둘째, list index range로 다수의 elements를 조회하는 함수이다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_get_by_range(memcached_st *ptr,
                            const char *key, size_t key_length,
@@ -275,8 +254,7 @@ Response code는 아래와 같다.
 조회 결과는 memcached_coll_result_t 구조체에 저장된다.
 조회 결과에 접근하기 위한 API는 다음과 같다.
 
-
-``` c
+```c
 memcached_coll_result_st *
 memcached_coll_result_create(const memcached_st *ptr, memcached_coll_result_st *result)
 void
@@ -294,56 +272,52 @@ size_t
 memcached_coll_result_get_value_length(memcached_coll_result_st *result, size_t index)
 ```
 
-List element를 조회하는 예제는 아래와 같다.
-
-``` c
-void arcus_list_element_get(memcached_st *memc)
-{
-    uint32_t flags= 10;
-    uint32_t exptime= 600;
-    uint32_t maxcount= 1000;
-
-    memcached_coll_create_attrs_st attributes;
-    memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
-    memcached_return_t rc;
-    memcached_coll_result_st *result;
-
-    for (uint32_t i=0; i<maxcount; i++) {
-        char buffer[15];
-        size_t buffer_len= snprintf(buffer, 15, "value%d", i);
-        rc= memcached_lop_insert(memc, "a_list", strlen("a_list"), i,
-                                 buffer, buffer_len, &attributes);
-        assert(MEMCACHED_SUCCESS == rc);
-    }
-
-    // 조회 범위에 아무런 element가 없는 경우
-    result = memcached_coll_result_create(memc, NULL);
-
-    rc= memcached_lop_get_by_range(memc, "a_list", strlen("a_list"),
-                                   maxcount, maxcount+maxcount, false, false, result);
-    assert(MEMCACHED_SUCCESS != rc);
-    assert(MEMCACHED_NOTFOUND_ELEMENT == memcached_get_last_response_code(memc));
-
-    memcached_coll_result_free(result);
-
-    // 조회와 동시에 조회된 element를 삭제한다. Empty 상태가 된 리스트는 삭제된다.
-    result = memcached_coll_result_create(memc, NULL);
+- 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 길이 정보를 가져온다.
 
-    rc= memcached_lop_get_by_range(memc, "a_list", strlen("a_list"),
-                                   0, maxcount, true, true, result);
-    assert(MEMCACHED_SUCCESS == rc);
-    assert(MEMCACHED_DELETED_DROPPED == memcached_get_last_response_code(memc));
+List element를 조회하는 예시는 아래와 같다.
 
-    // 조회 결과를 확인한다.
-    for (size_t i=0; i<memcached_coll_result_get_count(result); i++)
-    {
-        char buffer[15];
-        snprintf(buffer, 15, "value%u", (int)i);
-        assert(0 == strcmp(buffer, memcached_coll_result_get_value(result, i)));
-    }
-
-    // 조회 결과를 삭제한다.
-    memcached_coll_result_free(result);
+```c
+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);
+
+  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));
+    return -1;
+  }
+
+  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);
+  } */
+
+  memcached_coll_result_free(&result);
+  return 0;
 }
 ```
 
@@ -353,7 +327,7 @@ List에 여러 elements를 한번에 삽입하는 함수는 두 가지가 있다
 
 첫째, 하나의 key가 가리키는 list에 다수의 elements를 삽입하는 함수이다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_piped_insert(memcached_st *ptr,
                            const char *key, const size_t key_length,
@@ -371,9 +345,65 @@ memcached_lop_piped_insert(memcached_st *ptr,
 - values, values_length: 다수 element 각각의 value와 그 길이
 - attributes: 해당 list가 없을 시에, attributes에 따라 list를 생성 후에 삽입한다.
 
+하나의 key가 가리키는 list에 다수의 elements를 삽입하는 예시는 다음과 같다.
+
+```c
+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를 삽입하는 함수이다.
 
-``` c
+```c
 memcached_return_t
 memcached_lop_piped_insert_bulk(memcached_st *ptr,
                                 const char * const *keys, const size_t *key_length,
@@ -401,52 +431,57 @@ List element 일괄 삽입의 결과는 아래의 인자를 통해 받는다.
   - MEMCACHED_SOME_SUCCESS: 일부 element가 저장됨.
   - MEMCACHED_ALL_FAILURE: 전체 element가 저장되지 않음.
 
-List element 일괄 삽입의 예제는 아래와 같다.
+여러 key들이 가리키는 list들에 각각 하나의 element를 삽입하는 예시는 아래와 같다.
 
-``` c
-void arcus_list_element_piped_insert(memcached_st *memc)
+```c
+int arcus_list_element_piped_insert_bulk(memcached_st *memc)
 {
-    uint32_t flags= 10;
-    uint32_t exptime= 600;
-    uint32_t maxcount= MEMCACHED_COLL_MAX_PIPED_CMD_SIZE;
-
-    memcached_coll_create_attrs_st attributes;
-    memcached_coll_create_attrs_init(&attributes, flags, exptime, maxcount);
-
-    memcached_return_t rc;
-    memcached_return_t piped_rc; // pipe operation의 전체 성공 여부
-    memcached_return_t results[MEMCACHED_COLL_MAX_PIPED_CMD_SIZE]; // 각 key에 대한 응답코드
-
-    // 테스트 데이터
-    int32_t indexes[MEMCACHED_COLL_MAX_PIPED_CMD_SIZE];
-    char **values = (char **)malloc(sizeof(char *) * MEMCACHED_COLL_MAX_PIPED_CMD_SIZE);
-    size_t valuelengths[MEMCACHED_COLL_MAX_PIPED_CMD_SIZE];
-
-    for (uint32_t i=0; i<maxcount; i++)
-    {
-        indexes[i] = i;
-        values[i]= (char *)malloc(sizeof(char) * 15);
-        valuelengths[i]= snprintf(values[i], 15, "value%d", i);
-    }
-
-
-    // piped insert를 요청한다.
-    rc= memcached_lop_piped_insert(memc, "a_list", strlen("a_list"),
-            MEMCACHED_COLL_MAX_PIPED_CMD_SIZE,
-            indexes, values, valuelengths,
-            &attributes, results, &piped_rc);
-
-    assert(MEMCACHED_SUCCESS == rc);
-    assert(MEMCACHED_ALL_SUCCESS == piped_rc);
-
-    // 각 key에 대한 결과를 확인한다.
-    for (size_t i=0; i<maxcount; i++)
-    {
-        assert(MEMCACHED_STORED == results[i] or MEMCACHED_CREATED_STORED == results[i]);
+  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]));
+      }
     }
+  }
 
-    for (uint32_t i=0; i<maxcount; i++)
-        free((void *)values[i]);
-    free((void *)values);
+  assert(rc == MEMCACHED_SUCCESS || rc == MEMCACHED_SOME_ERRORS);
+  return 0;
 }
 ```