> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/development/api-reference/classes/memorystorehashmap.md).

# MemoryStoreHashMap

MemoryStoreHashMap : `Instance`

## Overview

MemoryStoreHashMap은 같은 월드의 여러 서버가 공유하는 키-값 형태의 메모리 저장소입니다. 서버 간에 최신 상태를 빠르게 주고받아야 하는 데이터를 키 단위로 저장하고 조회할 때 사용합니다.

MemoryStoreService:GetHashMap() 메서드를 통해서만 가져올 수 있으며, Instance.new()로 생성할 수 없습니다.

이 객체는 서버 Script에서만 사용할 수 있으며, LocalScript에서 호출하면 오류가 발생합니다.

**저장 규칙**

* 키는 1 \~ 128자의 문자열이어야 합니다.
* 값은 직렬화했을 때 1 \~ 32,768바이트여야 합니다. 순환 참조가 있는 테이블이나 저장할 수 없는 타입의 값을 저장하면 오류가 발생합니다.
* 모든 항목에는 만료 시간(초)이 있으며, 0 \~ 3,888,000초(45일) 범위로 지정합니다. 만료된 항목은 없는 항목과 같이 취급됩니다.

**주의사항**

* 휘발성 저장소이므로 저장소가 재시작되면 데이터가 사라질 수 있습니다.
* 캐시를 사용하지 않으므로 모든 읽기와 쓰기는 호출할 때마다 새로 요청됩니다.
* 이 객체의 Async 메서드는 결과를 받을 때까지 호출한 스크립트를 일시 중단(yield)합니다. 요청이 실패하면 오류가 발생하므로 pcall로 감싸 호출하는 것이 좋습니다.

## Properties

## Methods

### GetAsync

지정한 키에 저장된 값을 반환합니다.

키에 해당하는 항목이 없거나 만료되었으면 오류 없이 nil을 반환합니다. 서버 오류 등으로 요청이 실패하면 nil을 반환하지 않고 오류가 발생합니다.

이 메서드는 결과를 받을 때까지 호출한 스크립트를 일시 중단(yield)합니다.

#### Parameters

| `string` InKey | 값을 가져올 항목의 키입니다. 1 \~ 128자여야 합니다. |
| -------------- | --------------------------------- |

#### Return

| `Value` | 키에 저장된 값입니다. 항목이 없거나 만료되었으면 nil입니다. |
| ------- | ----------------------------------- |

#### Code Samples

### ListItemsAsync

저장된 항목을 페이지 단위로 순회할 수 있는 MemoryStoreHashMapPages 객체를 반환합니다.

이 메서드는 첫 페이지를 받을 때까지 호출한 스크립트를 일시 중단(yield)합니다.

**주의사항**

* 순회 결과는 조회 시점의 고정된 사본이 아닙니다. 순회 도중 추가된 항목은 나올 수도 있고 나오지 않을 수도 있으며, 같은 항목이 두 번 이상 나올 수 있습니다. 다만 순회하는 동안 계속 존재한 항목은 적어도 한 번은 나옵니다.
* 페이지에 담긴 항목이 지정한 개수보다 적어도 마지막 페이지라는 뜻은 아닙니다. 마지막 여부는 IsFinished로 확인해야 합니다.

#### Parameters

| `number` InCount | <p>한 페이지에 담을 최대 항목 수입니다.</p><ul><li>1 \~ 200 사이의 값을 지정해야 하며, 범위를 벗어나면 오류가 발생합니다.</li><li>지정한 값은 최대치이며, 한 페이지에 항상 그만큼 담기는 것은 아닙니다.</li></ul> |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |

#### Return

| `MemoryStoreHashMapPages` | <p>저장된 항목을 페이지 단위로 담은 MemoryStoreHashMapPages 객체입니다.</p><ul><li>GetCurrentPage()는 key와 value 필드를 가진 테이블의 배열을 반환합니다.</li><li>저장된 항목이 없으면 GetCurrentPage()는 빈 테이블을 반환합니다.</li></ul> |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

### RemoveAsync

지정한 키의 항목을 삭제합니다.

존재하지 않는 키를 삭제해도 오류 없이 성공합니다.

이 메서드는 삭제가 완료될 때까지 호출한 스크립트를 일시 중단(yield)합니다.

#### Parameters

| `string` InKey | 삭제할 항목의 키입니다. 1 \~ 128자여야 합니다. |
| -------------- | ------------------------------ |

#### Return

| `Value` | 반환값이 없습니다(nil). |
| ------- | --------------- |

#### Code Samples

### SetAsync

지정한 키에 값을 저장합니다. 키에 이미 값이 있으면 조건 없이 덮어씁니다.

만료 시간은 저장할 때마다 새로 적용되므로, 계속 갱신되는 항목은 만료되지 않고 유지됩니다.

이 메서드는 저장이 완료될 때까지 호출한 스크립트를 일시 중단(yield)합니다. 저장에 실패하면 오류가 발생합니다.

#### Parameters

| `string` InKey       | 값을 저장할 항목의 키입니다. 1 \~ 128자여야 합니다.                                                                                                                                             |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` InValue      | <p>저장할 값입니다.</p><ul><li>직렬화했을 때 1 \~ 32,768바이트여야 합니다.</li><li>생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul>                                                                            |
| `Value` InExpiration | <p>항목의 만료 시간(초)입니다.</p><ul><li>0 \~ 3,888,000초(45일) 사이의 값을 지정해야 하며, 소수도 지정할 수 있습니다.</li><li>0을 지정하면 항목이 즉시 만료되어 삭제됩니다.</li><li>기본값이 없으므로 생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul> |

#### Return

| `Value` | 저장하기 전에 키에 항목이 이미 있었으면 true, 없었으면 false입니다. |
| ------- | ------------------------------------------- |

#### Code Samples

### UpdateAsync

지정한 키의 현재 값을 읽어 콜백 함수로 변환한 뒤, 그 결과를 저장합니다.

값을 읽은 뒤 저장하기 전에 다른 서버나 스크립트가 같은 키를 변경하면, 최신 값을 다시 읽어 콜백을 다시 실행합니다. 이 재시도는 최대 5회 또는 10초까지 수행되며, 그 안에 저장하지 못하면 오류가 발생합니다.

이 메서드는 저장이 완료될 때까지 호출한 스크립트를 일시 중단(yield)합니다.

**주의사항**

* 콜백은 재시도할 때마다 다시 실행되므로 실행 횟수가 보장되지 않습니다. 콜백 안에서 외부 동작을 수행하지 않아야 합니다.
* 콜백 안에서 오류가 발생하면 값은 변경되지 않고 UpdateAsync에서 오류가 발생합니다.
* 콜백 안에서 같은 키에 대해 다시 UpdateAsync를 호출하면 오류가 발생합니다.
* 만료 시간은 기존 항목의 만료 시간을 유지하지 않고, 갱신할 때마다 InExpiration 값으로 새로 적용됩니다.

#### Parameters

| `string` InKey              | 값을 갱신할 항목의 키입니다. 1 \~ 128자여야 합니다.                                                                                                                                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` InTransformFunction | <p>현재 값을 받아 새 값을 반환하는 함수입니다.</p><ul><li>항목이 없거나 만료되었으면 nil을 인자로 받습니다.</li><li>nil을 반환하면 갱신을 취소하며, 이때 UpdateAsync는 오류 없이 nil을 반환합니다.</li><li>반환한 값을 저장할 수 없으면(순환 참조 테이블, 저장할 수 없는 타입, 32,768바이트 초과 등) 오류가 발생합니다.</li><li>함수가 아닌 값을 전달하면 오류가 발생합니다.</li></ul> |
| `Value` InExpiration        | <p>갱신된 항목의 만료 시간(초)입니다.</p><ul><li>0 \~ 3,888,000초(45일) 사이의 값을 지정해야 합니다.</li><li>항목이 이미 있어도 이 값이 새 만료 시간으로 적용됩니다.</li><li>0을 지정하면 항목이 즉시 만료되어 삭제됩니다.</li><li>기본값이 없으므로 생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul>                                                 |

#### Return

| `Value` | 저장된 새 값입니다. 콜백이 nil을 반환해 갱신을 취소했으면 nil입니다. |
| ------- | ------------------------------------------ |

#### Code Samples

## Events
