DOC: Add examples for the KV API

[ing-eoking]

🔗 Related Issue

• jam2in/arcus-works#606

⌨️ What I did

• KV 문서에 예제 코드를 추가했습니다.
• libmemcached 문서를 확인했으나 예제 코드가 따로 존재하지 않아 저희 쪽 다른 문서를 참고했습니다.

[namsic]

https://github.com/ing-eoking/arcus-c-client/blob/kvdoc/docs/03-key-value-API.md#key-value-item-저장

[jhpark816]

@ing-eoking 아래 메뉴얼도 참고하여, 설명을 보강하는 작업도 다른 PR로 진행하면 좋겠습니다. https://docs.oracle.com/cd/E88353_01/html/E37842/memcached-get-3libmemcached.html

[namsic]

@jhpark816

현재 PR은 기존 문서와 유사한 구조를 갖도록 작성되었는데요. (assert 등) 만약 이러한 구조가 적절하지 않다면 이 PR의 내용만 수정하는 것으로는 충분하지 않습니다. 수정된 내용에 맞게 기존 모든 문서를 다시 정리해야 하는데, 이 PR에서 문서 구조를 결정하기보다는 별도의 이슈를 만들어 의견이 충분히 정리된 뒤에 일괄 적용하는 것이 좋겠습니다.

개인적으로는, 실패 시 처리 방법 등은 특정 API에 국한되는 것이 아니므로 함수마다 예외 처리하는 예시를 매 번 작성해 두는 것은 비효율이라고 봅니다. 한 가지 수정 사항이 생길 때마다 모든 API 문서를 함께 변경해야 할 것이고, 시간이 흐르면 문서 간 일관성이 깨져 이를 맞추는 작업을 다시 진행하게 될 것입니다.

캐시 서버의 문서처럼 각 함수의 결과로 반환될 수 있는 rc 목록과 그 의미 정도만 나열해 두고, 예외 처리 및 로깅 등은 ARCUS C Client와 같은 공통 문서에 작성해 두면 충분할 것입니다.

아래 메뉴얼도 참고하여, 설명을 보강하는 작업도 다른 PR로 진행하면 좋겠습니다. https://docs.oracle.com/cd/E88353_01/html/E37842/memcached-get-3libmemcached.html

위 링크의 내용 자체는 arcus-c-client에도 있는 내용입니다. 만약 링크와 같은 형태의 메뉴얼이 필요하다면, 이미 있는 내용을 중복으로 작성할 것이 아니라 man2html과 같은 도구를 사용하는 것으로 충분할 것입니다.

[jhpark816]

@ing-eoking 본 작업도 진행해 주세요.

예시 코드를 통해 보이고자 하는 사항은

• API 사용법
• 리턴 값의 사용법 (성공, 실패)

위 사항을 보이는 예시 코드를 하나 준비하여 리뷰 및 논의를 거쳐 예시 코드 형태를 결정하고, 그 형태로 일괄 적용하시죠.

[ing-eoking]

@jhpark816

현재 해당 PR에 대하여 제가 생각하고 있는 예시는 아래와 같습니다.

int arcus_kv_store(memcached_st *memc)
{
  const char *key= "item:a_key";
  const char *value= "value";
  uint32_t exptime= 600;
  uint32_t flags= 0;
  memcached_return_t rc;

  rc= memcached_set(memc, key, strlen(key), value, strlen(value), exptime, flags);
  if (memcached_failed(rc)) {
    fprintf(stderr, "Failed to memcached_set: %d(%s)\n", rc, memcached_strerror(mc, rc));
    return -1;
  }

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

리턴 값의 사용법 (성공, 실패)

성공과 실패의 판단 기준을 함수의 리턴 값보다는 API에서 제공하는 에러값에 두는 것이 더 적절하다고 생각합니다.

예를 들어, memcached_get 명령어를 수행했을 때 반환된 에러값이 MEMCACHED_SUCCESS인 경우, value가 NULL이고 value_length가 0이라면, 이는 성공적인 수행이지만 데이터가 없음을 의미합니다.

이에 대한 예제는 다른 성공과 동일하게 처리하면 되지 않을까 생각합니다.

fprintf(stdout, "[DEBUG] memcached_get: %.*s=%.*s\n", key_len, key, value_len, value);

[ing-eoking]

@jhpark816 @namsic

변경된 코드 보시고, 리뷰 진행해주시면 될 것 같습니다.

[ing-eoking]

@namsic

예시 코드 추가 외 다른 설명은 현재 상태로 충분하다고 보는 것인가요?

개인적으로 소제목을 하나 더 두는 편이 더 깔끔해보여 변경해보았습니다. 리뷰 진행해주시면 될 것 같습니다.

아래는 예시입니다.

---

Key-Value Item 저장

key-value item을 저장하는 API로 set, add, replace, prepend/append가 있다

주요 파라미터

• expiration: ...
• flags: ...

함수 설명

새로운 아이템을 저장하거나 교체하는 API는 다음과 같다.

memcached_return_t memcached_set(...)
memcached_return_t memcached_add(...)
memcached_return_t memcached_replace(...)

• memcached_set: ...
• memcached_add: ...
• memcached_replace: ...

  예제 코드

대표적으로 set을 활용하는 예제는 다음과 같다.

int arcus_kv_store(memcached_st *memc)
{
  ...
}

Key-Value Item 조회

...

Key-Value 제거

...

[jhpark816]

@namsic 리뷰 완료한 상태가 아니죠?

[namsic]

리뷰 완료한 상태가 아니죠?

예. 아직 확인 중 입니다.

[ing-eoking]

@jhpark816

mget에서 값이 빈 문자열인 경우 NULL이 반환되는 원인 분석

(이 문제는 get에서도 동일하게 발생합니다.)

memcached_fetch 함수를 살펴보면, 아래와 같이 result 구조체 내에서 값을 가져와 문자열 형태로 반환합니다.

char *memcached_fetch(...)
{
  ...
  return memcached_string_take_value(&result_buffer->value);
}

memcached_string_take_value 함수 내부는 다음과 같이 구현되어 있습니다.

char *memcached_string_take_value(memcached_string_st *self)
{
  assert_msg(self, "Invalid memcached_string_st");
  // If we fail at adding the null, we copy and move on
  if (memcached_success(memcached_string_append_null(self)))
  {
    return memcached_string_c_copy(self);
  }

  char *value= self->string;

  _init_string(self);

  return value;
}

이 함수는 문자열 끝에 null 문자를 성공적으로 추가할 경우(실패 케이스는 모르겠습니다), memcached_string_c_copy를 호출하여 복사한 값을 반환합니다.

memcached_string_c_copy 함수는 다음과 같이 구현되어 있습니다.

char *memcached_string_c_copy(memcached_string_st *string)
{
  if (not memcached_string_length(string))
    return NULL;

  char *c_ptr= static_cast<char *>(libmemcached_malloc(string->root, (memcached_string_length(string)+1) * sizeof(char)));

  if (not c_ptr)
    return NULL;

  memcpy(c_ptr, memcached_string_value(string), memcached_string_length(string));
  c_ptr[memcached_string_length(string)]= 0;

  return c_ptr;
}

첫 번째 조건문에서 memcached_string_length가 0일 경우 NULL이 반환되도록 되어 있습니다.

[jhpark816]

최신 libmemcached도 동일하게 처리하고 있나요?

[ing-eoking]

@jhpark816

최신 libmemcached도 동일하게 처리하고 있나요?

로직은 조금 변경되었지만 길이가 0이면, NULL을 반환하는 동작 자체는 동일합니다.

char *memcached_string_take_value(memcached_string_st *self) {
  char *value = NULL;

  assert_msg(self, "Invalid memcached_string_st");
  if (self) {
    if (memcached_string_length(self)) {
      // If we fail at adding the null, we copy and move on
      if (memcached_failed(memcached_string_append_null(self))) {
        return NULL;
      }

      value = self->string;
      _init_string(self);
    }
  }

  return value;
}

[ing-eoking]

fetch가 실패할 경우 반환되는 에러는 다음과 같습니다. (아직 확실하지는 않지만, 대부분의 상황에서 아래의 에러만 반환되는 것으로 보입니다.)

MEMCACHED_NOTFOUND : 모든 서버에서 읽을 수 있는 결과가 없는 경우에 반환됩니다. MEMCACHED_CONNECTION_FAILURE : 특정 서버와의 연결에 문제가 있는 경우(예: 잘못된 소켓 파일) 반환됩니다.

특히 MEMCACHED_CONNECTION_FAILURE가 발생하더라도, 다른 서버에서 읽을 수 있는 결과가 있는 경우에는 MEMCACHED_SUCCESS로 처리됩니다.

[jhpark816]

mget 실패하는 경우가 failure, some_errros 2가지 아닌가요? 다른 경우의 오류를 설명하는 가요?

그래서, get, mget 예시 코드는 어떻게 하면 되나요?

[ing-eoking]

@jhpark816

mget 실패하는 경우가 failure, some_errros 2가지 아닌가요? 다른 경우의 오류를 설명하는 가요?

제가 잘못 작성했네요. fetch에 대한 설명이었습니다. 결론적으로, fetch 수행 과정에서 실패할 경우에는 나머지 연산을 계속 진행하지 않고 바로 리턴하는 것이 더 나을 것 같습니다.

[ing-eoking]

@jhpark816

에러 처리를 value == NULL 혹은 memcached_failed(rc) 중 어떤 방식은 활용하는가?

빈 문자열을 저장하는 경우 value가 NULL인 경우가 발생하므로 memcached_failed(rc) 가 적합합니다.

memcached_fetch 중 에러가 발생하는 경우 중지하지 말고, 계속 진행하는 것이 맞는지?

일반적으로 memcached_fetch 에서 memcached_failed를 통해 에러로 감지되는 에러는 MEMCACHED_NOTFOUND와 MEMCACHED_CONNECTION_FAILURE 입니다.

두 에러 모두 더 이상 성공적으로 값을 읽을 수 없는 경우에 반환되는 것으로 보이기에 바로 리턴하는 편이 좋을 것 같습니다.

그래서, get, mget 예시 코드는 어떻게 하면 되나요?

현재 PR에 반영된 상태로 가는 편이 좋다고 생각합니다.

int arcus_kv_get(memcached_st *memc)
{
  const char *key= "item:a_key";
  const char *value;
  size_t value_length;
  uint32_t flags;
  memcached_return_t rc;

  value= memcached_get(memc, key, strlen(key), &value_length, &flags, &rc);
  if (memcached_failed(rc)) {
    fprintf(stderr, "Failed to memcached_get: %d(%s)\n", rc, memcached_strerror(mc, rc));
    return -1;
  }

  assert(rc == MEMCACHED_SUCCESS);
  if (value != NULL) {
    fprintf(stdout, "memcached_get: %s=%s\n", key, value);
    free((void*)value);
  } else {
    fprintf(stdout, "memcached_get: %s=<empty value>.\n", key);
  }
  return 0;
}

int arcus_kv_mget(memcached_st *memc)
{
  const char * const keys[]= { "item:a_key1", "item:a_key2", "item:a_key3" };
  size_t keys_len[3];
  size_t number_of_keys = 3;
  uint32_t flags;
  memcached_return_t rc;

  for (size_t i=0; i<number_of_keys; i++)
  {
    keys_len[i]= strlen(keys[i]);
  }

  rc= memcached_mget(memc, keys, keys_len, number_of_keys);
  if (rc == MEMCACHED_FAILURE) {
    fprintf(stderr, "Failed to memcached_get: %d(%s)\n", rc, memcached_strerror(mc, rc));
    return -1;
  }

  assert(rc == MEMCACHED_SUCCESS || rc == MEMCACHED_SOME_ERRORS);
  while (true)
  {
    char key[MEMCACHED_MAX_KEY];
    size_t key_length;
    size_t value_length;

    char *value= memcached_fetch(mc, key, &key_length, &value_length, &flags, &rc);
    if (memcached_failed(rc)) {
      fprintf(stderr, "Failed to memcached_fetch: %d(%s)\n", rc, memcached_strerror(mc, rc));
      return -1;
    }

    if (rc == MEMCACHED_END) {
      break;
    }

    assert(rc == MEMCACHED_SUCCESS);
    if (value != NULL) {
      fprintf(stdout, "memcached_mget: %s=%s\n", key, value);
      free((void*)value);
    } else {
      fprintf(stdout, "memcached_mget: %s=<empty value>.\n", key);
    }
  }
  return 0;
}

[ing-eoking]

@jhpark816 @namsic

리뷰 부탁드립니다.

[ing-eoking]

@jhpark816

일괄 수정되었습니다.

[jhpark816]

@ing-eoking cas 연산은 별도 PR로 추가해 주시죠.