DOC: Restructure markdown documentation directory

naver · Oct 20, 2023 · e980009 · e980009
1 parent 4b5e3b8
commit e980009
Show file tree

Hide file tree

Showing 18 changed files with 3,345 additions and 0 deletions.
diff --git a/documentation/README.md b/documentation/README.md
@@ -0,0 +1 @@
+ch01-arcus-basic-concept.md
diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md
@@ -0,0 +1,23 @@
+# Table of contents
+
+* [Basic concept](ch01-arcus-basic-concept.md)
+* [Collection items](ch02-collection-items.md)
+* [Item attributes](ch03-item-attributes.md)
+
+## Manuals
+* [Commandline arguments](manuals/commandline_arguments.md)
+* [Compilation faq](manuals/compilation_faq.md)
+
+## Reference
+* [ascii protocol](ascii-protocol/ch00-arcus-ascii-protocol.md)
+  * [Telnet interface](ascii-protocol/ap01-arcus-telnet-interface.md)
+  * [Key-Value](ascii-protocol/ch04-command-key-value.md)
+  * [List](ascii-protocol/ch05-command-list-collection.md)
+  * [Set](ascii-protocol/ch06-command-set-collection.md)
+  * [Map](ascii-protocol/ch07-command-map-collection.md)
+  * [B+Tree](ascii-protocol/ch08-command-btree-collection.md)
+  * [Pipelining](ascii-protocol/ch09-command-pipelining.md)
+  * [Item attribute](ascii-protocol/ch10-command-item-attribute.md)
+  * [Scan](ascii-protocol/ch11-command-scan.md)
+  * [Administraion](ascii-protocol/ch12-command-administration.md)
+
diff --git a/documentation/ascii-protocol/ap01-arcus-telnet-interface.md b/documentation/ascii-protocol/ap01-arcus-telnet-interface.md
@@ -0,0 +1,116 @@
+# ARCUS Telnet Interface
+
+ARCUS cache server의 동작을 간단히 확인하는 방법으로, telnet interface를 이용할 수 있다.
+
+## Telnet 사용법
+
+OS prompt 상에서 아래와 같이 telnet 명령을 실행시킨다.
+telnet 명령의 인자로는 연결하고자 하는 ARCUS cache server인 memcached의 IP와 port number를 준다.
+
+```
+$ telnet {memcached-ip} {memcached-port}
+```
+
+## Telnet 연결
+
+Localhost에 11211 포트 번호로 memcached가 구동되어 있다고 가정한다.
+telnet 명령으로 해당 memcached에 연결하기 위해,
+OS prompt 상에서 아래의 명령을 수행한다.
+
+```
+$ telnet localhost 11211
+Trying 127.0.0.1...
+Connected to localhost.localdomain (127.0.0.1).
+Escape character is '^]'.
+```
+
+telnet 명령으로 memcached에 연결한 이후에는 ARCUS ASCII 명령을 직접 수행해 볼 수 있다.
+아래에서 그 예들을 든다. ARCUS ASCII 명령의 자세한 설명은 [ARCUS cache server ascii protocol](ch00-arcus-ascii-protocol.md)을 참고하기 바란다.
+
+
+### 예제 1.  get/set
+
+하나의 key-value item으로 <"foo", "fooval">을 저장하기 위해, set 명령을 입력한다.
+
+```
+set foo 0 0 6
+fooval
+```
+
+set 명령의 수행 결과로 정상적으로 key-value item이 저장되었다는 string이 리턴된다.
+
+```
+STORED
+```
+
+저장된 foo item을 조회하기 위해, get 명령을 입력한다.
+
+
+```
+get foo
+```
+
+get 명령으로 조회한 foo item 결과는 아래와 같다.
+
+
+```
+VALUE foo 0 6
+fooval
+END
+```
+
+### 예제 2.  b+tree
+
+하나의 b+tree item을 생성하면서 5개의 elements를 추가하기 위해,
+아래의 5개 bop insert 명령을 차례로 수행한다.
+
+```
+bop insert bkey1 90 6 create 11 0 0
+datum9
+bop insert bkey1 70 6
+datum7
+bop insert bkey1 50 6
+datum5
+bop insert bkey1 30 6
+datum3
+bop insert bkey1 10 6
+datum1
+```
+
+5개 bop insert 명령의 수행 결과는 아래와 같다.
+
+
+```
+CREATED_STORED
+STORED
+STORED
+STORED
+STORED
+```
+
+b+tree에서 30부터 80까지의 bkey(b+tree key) range에 속하는 elements를 조회하기 위하여,
+bop get 명령을 입력한다.
+
+
+```
+bop get bkey1 30..80
+```
+
+bop get 명령으로 조회한 결과는 아래와 같다.
+
+
+```
+VALUE 11 3
+30 6 datum3
+50 6 datum5
+70 6 datum7
+END
+```
+
+## Telnet 종료
+
+현재의 telnet 연결을 종료하려면, quit 명령을 입력한다.
+
+```
+quit
+```
diff --git a/documentation/ascii-protocol/ch00-arcus-ascii-protocol.md b/documentation/ascii-protocol/ch00-arcus-ascii-protocol.md
@@ -0,0 +1,66 @@
+# ARCUS Cache Server ASCII Protocol
+
+ARCUS Cache Server가 제공하는 명령들의 ASCII Protocol을 기술한다.
+Binary protocol은 현재 지원하지 않으므로, 논의에서 제외한다.
+
+본 문서는 ARCUS cache client 개발자를 주 대상으로 하며,
+ARCUS Cache Server에 관심있는 독자의 경우도 참고할 수 있다.
+
+Collection Support
+------------------
+
+ASCII Protocol 관점에서 ARCUS Cache Server는 기존 memcached 기능 외에 collection 기능을 제공한다.
+하나의 data만을 가지는 simple key-value 외에도 여러 data를 구조화된 형태로 저장/조회할 수 있으며,
+제공하는 collection 유형은 아래와 같다.
+
+- list : 데이터들의 linked list 구조
+- set : 유일한 데이터들의 집합으로 membership 검사에 적합
+- map : \<field, value\>쌍으로 구성된 데이터들의 집합으로 field 기준의 hash 구조
+- b+tree : b+tree 키 기준으로 정렬된 데이터들의 집합으로 range scan 처리에 적합
+
+Basic Concepts
+--------------
+
+ARCUS Cache Server를 사용함에 있어 필요한 cache key, item, slab 등의 기본 용어와 개념은
+[ARCUS 기본 개념](../ch01-arcus-basic-concept.md)에서 설명하므로, 이를 먼저 읽어보길 권한다.
+
+ARCUS Cache Server가 제공하는 collection과 element 구조, b+tree key, element flag 등의
+중요 요소들은 [Collection 기본 개념](../ch02-collection-items.md)에서 소개한다.
+
+Collection 기능을 제공함에 따라 item 속성들이 확장되었으며,
+이들은 [Item 속성 설명](../ch03-item-attributes.md)에서 자세히 다룬다.
+
+Simple Key-Value 기능
+---------------------
+
+ARCUS Cache Server는 memcached 1.4 기준의 key-value 명령을 그대로 제공하며, 일부에 대해 확장된 명령을 제공한다.
+따라서, 기존 memcached 1.4에서 사용한 명령들은 ARCUS Cache Server에서도 그대로 사용 가능하다.
+[Key-Value 명령](ch04-command-key-value.md)에서 key-value 유형의 item에 대해 수행가능한 명령들을 소개한다.
+
+Collection 기능
+---------------
+
+Collection 명령의 자세한 설명은 아래를 참고 바랍니다.
+
+- [List collection 명령](ch05-command-list-collection.md)
+- [Set collection 명령](ch06-command-set-collection.md)
+- [Map collection 명령](ch07-command-map-collection.md)
+- [B+tree collection 명령](ch08-command-btree-collection.md)
+
+Collection 일부 명령들은 command pipelining 처리가 가능하며,
+[Command Pipelining 기능](ch09-command-pipelining.md)에서 설명한다.
+
+Item Attributes 기능
+--------------------
+
+Collection 지원으로 인해 item 유형이 다양해 졌으며, 다양한 item 유형에 따라 item attributes도 확장되었다.
+Item attributes를 조회하거나 변경하기 위하여 [Item Attribute 명령](ch10-command-item-attribute.md)을 제공한다.
+
+Scan 기능
+--------------------
+조건에 맞는 item 혹은 prefix 목록을 가져오는 기능으로 [Scan 명령](ch11-command-scan.md)을 제공한다.
+
+Admin & Monitoring 기능
+-----------------------
+
+ARCUS Cache Server의 운영 상에 필요한 기능들은 [Admin & Monitoring 명령](ch12-command-administration.md)으로 제공한다.
diff --git a/documentation/ascii-protocol/ch04-command-key-value.md b/documentation/ascii-protocol/ch04-command-key-value.md
@@ -0,0 +1,112 @@
+# Chapter 4. Simple Key-Value 명령
+
+ARCUS Cache Server는 memcached 1.4의 key-value 명령을 그대로 지원하며, 
+이에 추가하여 incr/decr 명령은 그 기능을 확장 지원한다.
+
+Simple key-value 명령들의 요약은 아래와 같다.
+이들 명령들의 자세한 정보는 [memcached 1.4의 기존 ASCII protocol](https://github.com/naver/arcus-memcached/blob/master/doc/protocol.txt)를 참고하기 바란다.
+
+## storage 명령
+
+set, add, replace, append, prepend, cas 명령이 있으며 syntax는 다음과 같다.
+
+```
+<command name> <key> <flags> <exptime> <bytes> [noreply]\r\n<data>\r\n
+cas <key> <flags> <exptime> <bytes> <cas unique> [noreply]\r\n<data>\r\n
+```
+
+Response string과 그 의미는 아래와 같다.
+
+| Response String      | 설명                     |
+|----------------------|------------------------ |
+| "STORED"             | 성공
+| "NOT_STORED"         | 연산 조건에 부합하지 않아 저장에 실패 함. ex) 이미 존재하는 key에 대해 add 연산,  존재하지 않는 key에 대해 replace, append, prepend 연산.
+| "NOT_FOUND"          | cas 연산의 key miss.
+| "EXISTS"             | cas 연산의 응답으로, 해당 아이템이 클라이언트의 마지막 fetch 이후 수정된 적이 있음을 뜻함.
+| "TYPE_MISMATCH"      | 해당 아이템이 key-value 타입이 아님.
+| "CLIENT_ERROR"       | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) bad command line format
+| "SERVER ERROR"       | 서버 측의 오류로 저장하지 못했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) out of memory
+
+## retrieval 명령
+
+하나의 cache item을 조회하는 get, gets 명령이 있으며, syntax는 다음과 같다.
+get 명령은 value만 조회하는 반면 gets 명령은 value와 함께 cas value도 조회한다.
+
+```
+get <key>\r\n
+gets <key>\r\n
+```
+
+한번에 여러 cache item들을 조회하기 위한 mget, mgets 명령이 있으며, syntax는 다음과 같다.
+mget, mgets 명령은 get, gets 처럼 mget 명령은 value만 조회하고 mgets 명령은 value와 함께 cas value도 조회한다.
+mget 명령은 1.11 버전부터 mgets 명령은 1.13 버전부터 제공한다.
+
+```
+mget <lenkeys> <numkeys>\r\n
+<"space separated keys">\r\n
+mgets <lenkeys> <numkeys>\r\n
+<"space separated keys">\r\n
+```
+- \<”space separated keys”\> - key list로, 스페이스(' ')로 구분한다.
+- \<lenkeys\>과 \<numkeys> - key list 문자열의 길이와 key 개수를 나타낸다.
+
+retrieval 명령이 정상 수행되었을 경우, Response string은 아래와 같이 구성된다.
+
+- key hit된 아이템 정보를 모두 출력
+- key miss된 아이템은 별도 response 없이 생략
+- 응답의 끝에 "END\r\n" 출력
+
+```
+VALUE <key> <flags> <bytes> [<cas unique>]\r\n
+<data block>\r\n\
+...
+END\r\n
+```
+
+실패시 string은 아래와 같다.
+
+
+| Response String      | 설명                     |
+|----------------------|------------------------ |
+| "CLIENT_ERROR"       | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) bad command line format
+| "SERVER ERROR"       | 서버 측의 오류로 조회하지 못했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) out of memory writing get response
+
+mget 명령에서 메모리 부족으로 일부 key에 대해서만 정상 조회한 후 실패한 경우, 전체 연산을 서버 에러 처리한다.
+
+## deletion 명령
+
+delete 명령이 있으며 syntax는 다음과 같다.
+
+```
+delete <key> [noreply]\r\n
+```
+
+Response string과 그 의미는 아래와 같다.
+
+| Response String      | 설명                     |
+|----------------------|------------------------ |
+| "DELETED"            | 성공
+| "NOT_FOUND"          | key miss
+| "CLIENT_ERROR"       | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) bad command line format
+
+## Increment/Decrement 명령
+
+incr, decr 명령이 있으며, syntax는 아래와 같다.
+ARCUS Cache Server는 이 명령을 확장하여,
+해당 key가 존재하지 않는 경우에 initial 값을 가지는 새로운 key-value item을 생성한다.
+
+```
+incr <key> <delta> [<flags> <exptime> <initial>] [noreply]\r\n
+decr <key> <delta> [<flags> <exptime> <initial>] [noreply]\r\n
+```
+
+성공시 Response string으로 incr, decr 연산을 적용한 값이 출력 된다.
+
+실패시 Response string과 의미는 아래와 같다.
+
+| Response String      | 설명                     |
+|----------------------|------------------------ |
+| "NOT_FOUND"          | key miss
+| "TYPE_MISMATCH"      | 해당 아이템이 key-value 타입이 아님
+| "CLIENT_ERROR"       | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) invalid numeric delta argument, cannot increment or decrement non-numeric value
+| "SERVER ERROR"       | 서버 측의 오류로 연산하지 못했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) out of memory