> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 비동기 Lobby 및 Matchmaking C++ SDK 작업 가이드

> PlayFab Lobby 및 Matchmaking C++ SDK의 비동기 작업, 폴링 및 상태 변경 알림을 이해하고, 멀티플레이어 타이틀에 대한 모범 사례를 확인하세요.

# 비동기 작업 및 알림

느리거나 계산 비용이 많이 드는 작업의 경우, PlayFab Lobby and Matchmaking SDK는 비동기 API를 제공합니다. 비동기 API를 사용하면 메인 스레드에서 비용이 많이 들거나 느린 작업을 시작하고, 원하는 스레드에서 해당 작업의 완료를 폴링할 수 있습니다. 이 동일한 폴링 메커니즘은 SDK 업데이트의 비동기 알림을 타이틀 코드에 전달하는 데에도 사용됩니다. 이 페이지에서는 PlayFab Lobby and Matchmaking SDK의 비동기 API 패턴 및 이를 대상으로 프로그래밍하는 모범 사례에 대한 개요를 제공합니다.

## 기본 API 패턴

PlayFab Lobby and Matchmaking SDK에서 알아야 할 두 가지 유형의 비동기 API 패턴이 있습니다.

1. [비동기 작업](#asynchronous-operations)
2. [비동기 알림](#asynchronous-notifications)

### 비동기 작업

SDK의 비동기 API를 사용하는 것은 간단합니다. 비동기 작업을 시작하고 완료하는 일반적인 패턴은 다음과 같습니다.

1. 원하는 적절한 비동기 API에 대한 일반 메서드 호출을 수행합니다. 자주 사용하게 될 일반적인 비동기 작업은 다음과 같습니다.
   * [PFMultiplayerCreateAndJoinLobby](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayercreateandjoinlobby).
   * [PFMultiplayerJoinLobby](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerjoinlobby).
   * [PFLobbyPostUpdate](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pflobbypostupdate).
   * [PFMultiplayerCreateMatchmakingTicket](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayercreatematchmakingticket).

2. **SUCCEEDED()** 또는 **FAILED()** 매크로로 API의 **HRESULT** 반환 값을 확인합니다. 이 동기적으로 반환된 값은 작업이 성공적으로 시작되었는지 여부를 알려줍니다.

<Warning>
  비동기 API 호출의 동기 반환 값은 작업이 성공적으로 완료되었는지 여부를 알려주지 **않습니다**. 동기 대 비동기 오류에 대한 자세한 내용은 SDK의 [오류 처리 문서](/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-errors#synchronous-vs-asynchronous-errors)를 참조하세요.
</Warning>

3. [PFMultiplayerStartProcessingLobbyStateChanges()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerstartprocessinglobbystatechanges) 또는 [PFMultiplayerStartProcessingMatchmakingStateChanges](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges)에 의해 제공되는 관련 작업의 "완료 상태 변경"을 찾아 비동기 작업의 완료를 폴링합니다. **PFMultiplayerCreateAndJoinLobby()** 에 대한 관련 "완료 상태 변경"의 예는 [PFLobbyCreateAndJoinLobbyCompletedStateChange](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbycreateandjoinlobbycompletedstatechange)입니다. "상태 변경"이 무엇이며 어떻게 작동하는지에 대한 자세한 정보는 [State Changes](#state-changes) 섹션에서 확인할 수 있습니다.

4. 완료 상태 변경의 **result** 값을 확인하여 작업이 성공했는지 실패했는지 확인합니다. 이러한 오류 값에 대한 자세한 정보는 SDK의 [오류 처리 문서](/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-errors#synchronous-vs-asynchronous-errors)에서 찾을 수 있습니다.

### 비동기 알림

일부 기능은 Lobby 및 Matchmaking SDK의 변경 사항에 대한 비동기 알림을 생성합니다.

일반적인 알림은 다음과 같습니다.

1. [로비 업데이트 알림](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbyupdatedstatechange).
2. [로비 연결 해제 알림](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbydisconnectingstatechange).
3. [매치메이킹 티켓 상태 변경 알림](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange).

이러한 비동기 알림은 [PFMultiplayerStartProcessingLobbyStateChanges()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerstartprocessinglobbystatechanges) 및 [PFMultiplayerStartProcessingMatchmakingStateChanges](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges)를 통해 SDK가 "상태 변경"으로 제공합니다.

"상태 변경"이 무엇이며 어떻게 작동하는지에 대한 자세한 정보는 [State Changes](#state-changes) 섹션에서 찾을 수 있습니다.

## 상태 변경

Lobby 및 Matchmaking SDK의 비동기 API 모델은 [PFLobbyStateChange](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/structs/pflobbystatechange) 및 [PFMatchmakingStateChange](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingstatechange) 구조체를 중심으로 구축되어 있습니다. **PFLobbyStateChanges**는 로비 하위 시스템의 변경 사항을 알리고, **PFMatchmakingStateChanges**는 매치메이킹 하위 시스템의 변경 사항을 알립니다.

이러한 "상태 변경"은 SDK의 이벤트에 대한 비동기 알림입니다. 이 알림은 내부적으로 큐에 추가되며, [PFMultiplayerStartProcessingLobbyStateChanges()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pflobby/functions/pfmultiplayerstartprocessinglobbystatechanges) 및 [PFMultiplayerStartProcessingMatchmakingStateChanges](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges)를 호출하여 처리합니다. 이 함수는 각 API 하위 시스템에 대해 큐에 추가된 모든 상태 변경을 목록으로 반환하며, 이를 반복하여 개별적으로 처리할 수 있습니다. 각 상태 변경에는 해당 *stateChangeType* 필드가 있어 알림을 받고 있는 특정 상태 변경을 확인할 수 있습니다. 어떤 상태 변경이 제공되었는지 알게 되면, 해당 이벤트의 특정 데이터를 검사하기 위해 일반 **PFLobbyStateChange** 또는 **PFMatchmakingStateChange** 구조체를 더 구체적인 상태 변경 구조체 유형으로 캐스팅할 수 있습니다.

일반적으로 상태 변경 처리는 각 상태 변경을 핸들러에 위임하는 간단한 switch 문으로 구현됩니다.

**PFMultiplayerStartProcessingLobbyStateChanges** 또는 **PFMultiplayerStartProcessingMatchmakingStateChanges**에서 상태 변경 목록이 처리되면, 각각 [PFMultiplayerFinishProcessingMatchmakingStateChanges()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerfinishprocessingmatchmakingstatechanges) 또는 [PFMultiplayerFinishProcessingMatchmakingStateChanges()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerfinishprocessingmatchmakingstatechanges)에 반환되어야 합니다.

```cpp theme={null}
//
// Process Lobby state changes
//
uint32_t lobbyStateChangeCount;
const PFLobbyStateChange * const * lobbyStateChanges;
HRESULT hr = PFMultiplayerStartProcessingLobbyStateChanges(m_pfmHandle, &lobbyStateChangeCount, &lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < lobbyStateChangeCount; ++i)
{
    const PFLobbyStateChange* stateChange = lobbyStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFLobbyStateChangeType::CreateAndJoinLobbyCompleted:
        {
            HandleCreateAndJoinLobbyCompleted(
                static_cast<const PFLobbyCreateAndJoinLobbyCompletedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingLobbyStateChanges(m_pfmHandle, lobbyStateChangeCount, lobbyStateChanges);
if (FAILED(hr))
{
    return hr;
}

//
// Process Match state changes
//
uint32_t matchStateChangeCount;
const PFMatchmakingStateChange * const * matchStateChanges;
hr = PFMultiplayerStartProcessingMatchmakingStateChanges(m_pfmHandle, &matchStateChangeCount, &matchStateChanges);
if (FAILED(hr))
{
    return hr;
}

for (uint32_t i = 0; i < matchStateChangeCount; ++i)
{
    const PFMatchmakingStateChange* stateChange = matchStateChanges[i];
    switch (stateChange->stateChangeType)
    {
        case PFMatchmakingStateChangeType::TicketStatusChanged:
        {
            HandleMatchmakingTicketStatusChanged(
                static_cast<const PFMatchmakingTicketStatusChangedStateChange*>(stateChange));
            break;
        }
        // add other state change handlers here
    }
}

hr = PFMultiplayerFinishProcessingMatchmakingStateChanges(m_pfmHandle, matchStateChangeCount, matchStateChanges);
if (FAILED(hr))
{
    return hr;
}
```

## 비동기 작업 컨텍스트

각 비동기 API에는 `void* asyncContext` 매개 변수가 포함되어 있습니다. 이 값은 **PFMultiplayerStartProcessingLobbyStateChanges()** 또는 **PFMultiplayerStartProcessingMatchmakingStateChanges()** 에서 제공되면 이 API 호출과 관련된 완료 상태 변경에 설정되는 통과 매개 변수입니다.

이 값은 비동기 API 호출에 임의의 포인터 크기 컨텍스트를 첨부하는 메커니즘을 제공합니다. 이러한 컨텍스트는 다음을 포함한 많은 시나리오에서 사용될 수 있습니다.

1. SDK 호출과 타이틀별 데이터 연관
2. 공유 식별자로 여러 비동기 작업 연결

이러한 비동기 컨텍스트는 SDK 사용에 필수적이지는 않지만, 일부 타이틀 로직을 더 쉽게 작성할 수 있게 해줍니다.

## 작업 큐잉

비동기 API를 사용할 때 여러 비동기 작업이 더 큰 비동기 흐름의 일부로 순차적으로 실행되어야 하는 경우가 많습니다.

Lobby 및 Matchmaking SDK에서 한 가지 예는 로비를 만들고 해당 로비에 대한 초대를 친구들에게 보내는 것입니다. 직렬화되면 이 흐름은 다음과 같이 보입니다.

1. **PFMultiplayerCreateAndJoinLobby()** 를 호출하여 PlayFab 로비를 만들고 참여합니다.
2. 로비가 성공적으로 만들어지고 참여되었음을 반영하는 **PFLobbyCreateAndJoinLobbyCompletedStateChange**를 기다립니다.
3. 초대된 각 친구에 대해 **PFLobbySendInvite()** 를 호출합니다.
4. 초대가 성공적으로 전송되었음을 반영하는 **PFLobbySendInviteCompletedStateChange**를 기다립니다.

더 복잡한 흐름과 타이틀 로직의 경우, 이러한 직렬화된 패턴이 적절할 수 있습니다. 그러나 더 간단한 흐름의 경우, SDK는 타이틀 코드를 단순화하기 위한 대안을 제공합니다.

SDK의 많은 비동기 API는 이전 작업이 완전히 완료되기 전에 종속 작업의 큐잉을 지원합니다. 이전 예에서, 로비가 성공적으로 만들어진 것을 확인하기 전에 로비에 대한 초대를 보낼 수 있습니다.

효과적으로, 큐잉을 통해 비동기 작업 컬렉션을 함께 묶고, 한 번에 모두 시작하고, 오류 처리를 단일 실패 지점으로 통합할 수 있습니다.

```cpp theme={null}
PFLobbyHandle newLobby;
HRESULT hr = PFMultiplayerCreateAndJoinLobby(m_pfmHandle, myPlayerEntityId, newLobbyConfiguration, nullptr, nullptr, &newLobby);
if (SUCCEEDED(hr))
{
    for (size_t i = 0; SUCCEEDED(hr) && i < friends.size(); ++i)
    {
        hr = PFLobbySendInvite(m_pfmHandle, myPlayerEntityId, friends[i], nullptr);
    }

    if (SUCCEEDED(hr))
    {
        m_lobby = newLobby;
        Log("Created lobby and invited %zu friends!", friends.size());
    }
    else
    {
        // For the purposes of demonstration, we could have a policy that we shouldn't bother with any lobbies where
        // we couldn't invite all of our friends.
        (void) PFLobbyLeave(newLobby, myPlayerEntityId, nullptr);
    }
}
```

## 비동기 작업 제어

라이브러리와 타이틀의 핵심 CPU 워크로드 간의 CPU 경합을 피하기 위해 타이틀이 비동기 작업이 수행되는 위치를 제어해야 하는 경우가 있습니다.

Lobby 및 Matchmaking SDK를 사용하면 [스레드 선호도 제어](#controlling-thread-affinity)를 통해 비동기 작업이 실행되는 방식을 제어할 수 있습니다.

### 스레드 선호도 제어

기본적으로 비동기 SDK 작업은 신중하게 제어된 백그라운드 스레드에서 수행됩니다. 일부 타이틀은 CPU 경합을 피하기 위해 이러한 백그라운드 스레드가 예약되는 *위치*에 대한 대략적인 제어가 필요합니다.

이러한 타이틀을 위해 Lobby 및 Matchmaking SDK는 [PFMultiplayerSetThreadAffinityMask()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayersetthreadaffinitymask)를 제공합니다. 지원되는 플랫폼에서, 이를 통해 SDK의 백그라운드 스레드에 사용될 CPU 코어를 제한할 수 있습니다. 이렇게 하면 경합 없이 자체 CPU 워크로드용으로 특정 코어가 예약되도록 보장할 수 있습니다.


## Related topics

- [Lobby 및 Matchmaking C++ SDK 오류 처리](/ko/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-errors.md)
- [Lobby SDK 빠른 시작](/ko/services/playfab/multiplayer/lobby/lobby-getting-started.md)
- [빠른 시작 (Windows) - Party 및 Multiplayer](/ko/services/playfab/sdks/unified-sdk/quickstart-windows-party.md)
- [XBOX GDK로의 포팅 가이드](/ko/home/build-first-title/porting-guides.md)
- [PlayFab Unified SDK에서 메모리 관리](/ko/services/playfab/sdks/unified-sdk/memory-management.md)