> 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/memorystorequeue.md).

# MemoryStoreQueue

MemoryStoreQueue : `Instance`

## Overview

MemoryStoreQueue는 같은 월드의 여러 서버가 공유하는 우선순위 큐 형태의 메모리 저장소입니다. 매치메이킹 대기열이나 서버 간 작업 분배처럼, 여러 서버가 항목을 나눠 처리해야 할 때 사용합니다.

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

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

**항목 처리 흐름**

1. AddAsync로 항목을 큐에 추가합니다. 우선순위가 높은 항목이 먼저 나오고, 우선순위가 같으면 먼저 추가한 항목이 먼저 나옵니다.
2. ReadAsync로 항목을 읽어 옵니다. 읽어 온 항목은 큐에서 삭제되지 않고, GetQueue()에 지정한 숨김 시간 동안 다른 읽기에서 보이지 않게 됩니다.
3. 처리가 끝나면 ReadAsync가 반환한 읽기 ID를 RemoveAsync에 전달해 항목을 삭제합니다.
4. 숨김 시간이 지날 때까지 RemoveAsync를 호출하지 않으면 항목이 다시 큐에 나타납니다. 처리 도중 서버가 종료되어도 항목이 사라지지 않습니다.

**주의사항**

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

## Properties

## Methods

### AddAsync

큐에 값을 추가합니다.

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

#### Parameters

| `Value` InValue      | <p>큐에 추가할 값입니다.</p><ul><li>직렬화했을 때 1 \~ 32,768바이트여야 합니다.</li><li>순환 참조가 있는 테이블이나 저장할 수 없는 타입의 값을 전달하면 오류가 발생합니다.</li><li>생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul>         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Value` InExpiration | <p>항목의 만료 시간(초)입니다.</p><ul><li>0 \~ 3,888,000초(45일) 사이의 값을 지정해야 하며, 소수도 지정할 수 있습니다.</li><li>만료된 항목은 큐에서 제거됩니다.</li><li>기본값이 없으므로 생략하거나 nil을 전달하면 오류가 발생합니다.</li></ul> |
| `number` InPriority  | <p>(선택 사항) 항목의 우선순위입니다.</p><ul><li>값이 클수록 먼저 읽히며, 우선순위가 같으면 먼저 추가한 항목이 먼저 읽힙니다.</li><li>생략하면 0입니다.</li><li>NaN이나 무한대처럼 유한하지 않은 값을 전달하면 오류가 발생합니다.</li></ul>           |

#### Return

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

#### Code Samples

### GetSizeAsync

큐에 있는 항목의 개수를 반환합니다.

기본적으로 ReadAsync로 읽어 가 숨겨진 항목까지 포함해 셉니다. 만료된 항목은 개수에서 제외됩니다.

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

**주의사항**

* InExcludeInvisible을 true로 지정한 경우, 만료된 항목이 아직 정리되지 않았으면 실제보다 큰 값이 반환될 수 있습니다.

#### Parameters

| `boolean` InExcludeInvisible | <p>(선택 사항) 숨겨진 항목을 개수에서 제외할지 여부입니다.</p><ul><li>true이면 지금 읽을 수 있는 항목만 셉니다.</li><li>생략하면 false이며, 숨겨진 항목까지 포함해 셉니다.</li></ul> |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |

#### Return

| `Value` | 큐에 있는 항목의 개수(number)입니다. 아직 아무것도 추가되지 않은 큐는 0입니다. |
| ------- | ------------------------------------------------- |

#### Code Samples

### ReadAsync

큐에서 우선순위 순서대로 항목을 읽어 옵니다.

읽어 온 항목은 큐에서 삭제되지 않고, GetQueue()에 지정한 숨김 시간 동안 다른 읽기에서 보이지 않게 됩니다. 처리가 끝나면 반환된 읽기 ID를 RemoveAsync에 전달해 항목을 삭제해야 합니다.

큐에 읽을 항목이 없으면 InWaitTimeout 동안 약 2초 간격으로 다시 확인하며 기다립니다.

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

#### Parameters

| `number` InCount         | <p>(선택 사항) 읽어 올 최대 항목 수입니다.</p><ul><li>1 \~ 100 사이의 값을 지정해야 하며, 범위를 벗어나면 오류가 발생합니다.</li><li>생략하면 1입니다.</li></ul>                                         |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `boolean` InAllOrNothing | <p>(선택 사항) InCount만큼 항목을 채울 수 없을 때의 동작입니다.</p><ul><li>true이면 InCount만큼 읽을 수 없는 경우 아무 항목도 읽어 오지 않습니다.</li><li>생략하면 false이며, 읽을 수 있는 만큼만 읽어 옵니다.</li></ul> |
| `number` InWaitTimeout   | <p>(선택 사항) 읽을 항목이 없을 때 기다릴 최대 시간(초)입니다.</p><ul><li>0이면 한 번만 확인하고 즉시 반환합니다.</li><li>음수이면 항목이 생길 때까지 계속 기다립니다.</li><li>생략하면 -1이며, 계속 기다립니다.</li></ul>      |

#### Return

| `Tuple` | <p>읽어 온 항목과 읽기 ID를 함께 반환합니다.</p><ul><li>첫 번째 값은 읽어 온 값들의 배열입니다.</li><li>두 번째 값은 RemoveAsync에 전달할 읽기 ID(string)입니다.</li><li>읽어 온 항목이 없으면 빈 테이블이 아니라 두 값 모두 nil입니다.</li></ul> |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Code Samples

### RemoveAsync

ReadAsync로 읽어 온 항목을 큐에서 삭제해 처리 완료를 알립니다.

한 번의 ReadAsync로 읽어 온 항목은 하나의 묶음으로 삭제되며, 그중 일부만 삭제할 수는 없습니다. 처리하지 못한 항목이 있으면 RemoveAsync를 호출하지 않고 숨김 시간이 지나 항목이 큐로 돌아오기를 기다려야 합니다.

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

**주의사항**

* 숨김 시간이 지난 뒤에 이전 읽기 ID로 호출하면 항목은 삭제되지 않지만 오류 없이 성공으로 처리됩니다. 그 사이 다른 서버가 같은 항목을 읽어 갔을 수 있기 때문입니다.
* 같은 읽기 ID로 여러 번 호출해도 결과는 같습니다.

#### Parameters

| `string` InReadId | <p>ReadAsync가 두 번째 값으로 반환한 읽기 ID입니다.</p><ul><li>빈 문자열을 전달하면 오류가 발생합니다.</li></ul> |
| ----------------- | -------------------------------------------------------------------------------- |

#### Return

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

#### Code Samples

## Events
