비동기 작업 및 알림
느리거나 계산 비용이 많이 드는 작업의 경우, PlayFab Lobby and Matchmaking SDK는 비동기 API를 제공합니다. 비동기 API를 사용하면 메인 스레드에서 비용이 많이 들거나 느린 작업을 시작하고, 원하는 스레드에서 해당 작업의 완료를 폴링할 수 있습니다. 이 동일한 폴링 메커니즘은 SDK 업데이트의 비동기 알림을 타이틀 코드에 전달하는 데에도 사용됩니다. 이 페이지에서는 PlayFab Lobby and Matchmaking SDK의 비동기 API 패턴 및 이를 대상으로 프로그래밍하는 모범 사례에 대한 개요를 제공합니다.기본 API 패턴
PlayFab Lobby and Matchmaking SDK에서 알아야 할 두 가지 유형의 비동기 API 패턴이 있습니다.비동기 작업
SDK의 비동기 API를 사용하는 것은 간단합니다. 비동기 작업을 시작하고 완료하는 일반적인 패턴은 다음과 같습니다.- 원하는 적절한 비동기 API에 대한 일반 메서드 호출을 수행합니다. 자주 사용하게 될 일반적인 비동기 작업은 다음과 같습니다.
- SUCCEEDED() 또는 FAILED() 매크로로 API의 HRESULT 반환 값을 확인합니다. 이 동기적으로 반환된 값은 작업이 성공적으로 시작되었는지 여부를 알려줍니다.
- PFMultiplayerStartProcessingLobbyStateChanges() 또는 PFMultiplayerStartProcessingMatchmakingStateChanges에 의해 제공되는 관련 작업의 “완료 상태 변경”을 찾아 비동기 작업의 완료를 폴링합니다. PFMultiplayerCreateAndJoinLobby() 에 대한 관련 “완료 상태 변경”의 예는 PFLobbyCreateAndJoinLobbyCompletedStateChange입니다. “상태 변경”이 무엇이며 어떻게 작동하는지에 대한 자세한 정보는 State Changes 섹션에서 확인할 수 있습니다.
- 완료 상태 변경의 result 값을 확인하여 작업이 성공했는지 실패했는지 확인합니다. 이러한 오류 값에 대한 자세한 정보는 SDK의 오류 처리 문서에서 찾을 수 있습니다.
비동기 알림
일부 기능은 Lobby 및 Matchmaking SDK의 변경 사항에 대한 비동기 알림을 생성합니다. 일반적인 알림은 다음과 같습니다. 이러한 비동기 알림은 PFMultiplayerStartProcessingLobbyStateChanges() 및 PFMultiplayerStartProcessingMatchmakingStateChanges를 통해 SDK가 “상태 변경”으로 제공합니다. “상태 변경”이 무엇이며 어떻게 작동하는지에 대한 자세한 정보는 State Changes 섹션에서 찾을 수 있습니다.상태 변경
Lobby 및 Matchmaking SDK의 비동기 API 모델은 PFLobbyStateChange 및 PFMatchmakingStateChange 구조체를 중심으로 구축되어 있습니다. PFLobbyStateChanges는 로비 하위 시스템의 변경 사항을 알리고, PFMatchmakingStateChanges는 매치메이킹 하위 시스템의 변경 사항을 알립니다. 이러한 “상태 변경”은 SDK의 이벤트에 대한 비동기 알림입니다. 이 알림은 내부적으로 큐에 추가되며, PFMultiplayerStartProcessingLobbyStateChanges() 및 PFMultiplayerStartProcessingMatchmakingStateChanges를 호출하여 처리합니다. 이 함수는 각 API 하위 시스템에 대해 큐에 추가된 모든 상태 변경을 목록으로 반환하며, 이를 반복하여 개별적으로 처리할 수 있습니다. 각 상태 변경에는 해당 stateChangeType 필드가 있어 알림을 받고 있는 특정 상태 변경을 확인할 수 있습니다. 어떤 상태 변경이 제공되었는지 알게 되면, 해당 이벤트의 특정 데이터를 검사하기 위해 일반 PFLobbyStateChange 또는 PFMatchmakingStateChange 구조체를 더 구체적인 상태 변경 구조체 유형으로 캐스팅할 수 있습니다. 일반적으로 상태 변경 처리는 각 상태 변경을 핸들러에 위임하는 간단한 switch 문으로 구현됩니다. PFMultiplayerStartProcessingLobbyStateChanges 또는 PFMultiplayerStartProcessingMatchmakingStateChanges에서 상태 변경 목록이 처리되면, 각각 PFMultiplayerFinishProcessingMatchmakingStateChanges() 또는 PFMultiplayerFinishProcessingMatchmakingStateChanges()에 반환되어야 합니다.비동기 작업 컨텍스트
각 비동기 API에는void* asyncContext 매개 변수가 포함되어 있습니다. 이 값은 PFMultiplayerStartProcessingLobbyStateChanges() 또는 PFMultiplayerStartProcessingMatchmakingStateChanges() 에서 제공되면 이 API 호출과 관련된 완료 상태 변경에 설정되는 통과 매개 변수입니다.
이 값은 비동기 API 호출에 임의의 포인터 크기 컨텍스트를 첨부하는 메커니즘을 제공합니다. 이러한 컨텍스트는 다음을 포함한 많은 시나리오에서 사용될 수 있습니다.
- SDK 호출과 타이틀별 데이터 연관
- 공유 식별자로 여러 비동기 작업 연결
작업 큐잉
비동기 API를 사용할 때 여러 비동기 작업이 더 큰 비동기 흐름의 일부로 순차적으로 실행되어야 하는 경우가 많습니다. Lobby 및 Matchmaking SDK에서 한 가지 예는 로비를 만들고 해당 로비에 대한 초대를 친구들에게 보내는 것입니다. 직렬화되면 이 흐름은 다음과 같이 보입니다.- PFMultiplayerCreateAndJoinLobby() 를 호출하여 PlayFab 로비를 만들고 참여합니다.
- 로비가 성공적으로 만들어지고 참여되었음을 반영하는 PFLobbyCreateAndJoinLobbyCompletedStateChange를 기다립니다.
- 초대된 각 친구에 대해 PFLobbySendInvite() 를 호출합니다.
- 초대가 성공적으로 전송되었음을 반영하는 PFLobbySendInviteCompletedStateChange를 기다립니다.
