Skip to main content
비동기 API는 빠르게 반환되지만 비동기 작업을 시작하고 작업이 완료된 후 결과가 반환되는 API입니다. 전통적으로, 게임은 완료 콜백을 사용할 때 어떤 스레드가 비동기 작업을 실행하고 어떤 스레드가 결과를 반환하는지 거의 제어하지 못했습니다. 일부 게임은 스레드 동기화의 필요성을 피하기 위해 힙의 한 섹션이 단일 스레드에서만 액세스되도록 설계되었습니다. 완료 콜백이 게임이 제어하는 스레드에서 호출되지 않으면 비동기 작업의 결과로 공유 상태를 업데이트하려면 스레드 동기화가 필요합니다. PlayFab Unified SDK는 비동기 API 호출을 수행할 때 개발자에게 직접적인 스레드 제어를 제공하는 비동기 C API를 노출합니다. 다음은 PFProfilesGetProfileAsync를 호출하는 기본 예제입니다.
이 호출 패턴을 이해하려면 XAsyncBlockXTaskQueueHandle을 사용하는 방법을 이해해야 합니다. XAsyncBlock은 비동기 작업 및 완료 콜백과 관련된 모든 정보를 전달합니다. XTaskQueueHandle을 사용하면 어떤 스레드가 비동기 작업을 실행하고 어떤 스레드가 XAsyncBlock의 완료 콜백을 호출할지 결정할 수 있습니다.

XAsyncBlock

XAsyncBlock을 자세히 살펴보겠습니다. 다음과 같이 정의된 구조체입니다.
XAsyncBlock에는 다음이 포함됩니다.
  • queue - 작업을 실행할 위치에 대한 정보를 나타내는 핸들인 XTaskQueueHandle. 이 매개변수가 설정되지 않으면 기본 큐가 사용됩니다.
  • context - 콜백 함수에 데이터를 전달할 수 있습니다.
  • callback - 비동기 작업이 완료된 후 호출될 선택적 콜백 함수. 콜백을 지정하지 않으면 XAsyncGetStatusXAsyncBlock이 완료될 때까지 기다린 후 결과를 얻을 수 있습니다.
각 비동기 호출에 대해 힙에 새 XAsyncBlock을 만들어야 합니다. XAsyncBlockXAsyncBlock의 완료 콜백이 호출될 때까지 유지되어야 하며 그 후에 삭제할 수 있습니다.
중요: XAsyncBlock은 비동기 작업이 완료될 때까지 메모리에 남아 있어야 합니다. 동적으로 할당된 경우 XAsyncBlock의 완료 콜백 내부에서 삭제할 수 있습니다.

비동기 작업 대기

비동기 작업이 완료되었는지 알 수 있는 두 가지 방법이 있습니다.
  • XAsyncBlock의 완료 콜백이 호출됩니다.
  • XAsyncGetStatus를 true로 호출하여 완료될 때까지 기다립니다.
XAsyncGetStatus를 사용하면 XAsyncBlock의 완료 콜백이 실행된 후 비동기 작업이 완료된 것으로 간주됩니다. 그러나 XAsyncBlock의 완료 콜백은 선택 사항입니다. 비동기 작업이 완료되면 결과를 얻을 수 있습니다.

비동기 작업 결과 가져오기

결과를 얻기 위해, 대부분의 비동기 API 함수에는 비동기 호출의 결과를 받기 위한 해당 Result 함수가 있습니다. 예제 코드에서 PFProfilesGetProfileAsync에는 해당 PFProfilesGetProfileGetResult 함수가 있습니다. 이 함수를 사용하여 함수의 결과를 검색하고 그에 따라 조치를 취할 수 있습니다. 결과 검색에 대한 자세한 내용은 각 비동기 API 함수의 설명서를 참조하세요.

XTaskQueueHandle

XTaskQueueHandle을 사용하면 어떤 스레드가 비동기 작업을 실행하고 어떤 스레드가 XAsyncBlock의 완료 콜백을 호출할지 결정할 수 있습니다. 디스패치 모드를 설정하여 이러한 작업을 수행하는 스레드를 제어할 수 있습니다. 사용 가능한 세 가지 디스패치 모드가 있습니다.
  • Manual - 수동 큐는 자동으로 디스패치되지 않습니다. 개발자가 원하는 스레드에서 디스패치하는 것은 개발자의 책임입니다. 이를 사용하여 비동기 호출의 작업 또는 콜백 측을 특정 스레드에 할당할 수 있습니다.
  • Thread Pool - 스레드 풀을 사용하여 디스패치합니다. 스레드 풀은 스레드 풀 스레드가 사용 가능해짐에 따라 큐에서 호출을 가져와 병렬로 호출을 호출합니다. Thread Pool은 사용하기 가장 쉽지만 사용되는 스레드에 대한 제어가 가장 적습니다.
  • Serialized Thread Pool - 스레드 풀을 사용하여 디스패치합니다. 스레드 풀은 단일 스레드 풀 스레드가 사용 가능해짐에 따라 큐에서 호출을 가져와 직렬로 호출을 호출합니다.
  • Immediate - 큐에 대기 중인 작업을 제출한 스레드에서 즉시 디스패치합니다.
XTaskQueueHandle을 만들려면 XTaskQueueCreate를 호출해야 합니다. 예:
이 함수는 두 개의 XTaskQueueDispatchMode 매개변수를 사용합니다. XTaskQueueDispatchMode에는 세 가지 가능한 값이 있습니다.
workDispatchMode는 비동기 작업을 처리하는 스레드의 디스패치 모드를 결정합니다. completionDispatchMode는 비동기 작업 완료를 처리하는 스레드의 디스패치 모드를 결정합니다. XTaskQueueHandle을 만든 후에는 작업 및 완료 함수에 대한 스레딩을 제어하기 위해 XAsyncBlock에 추가하기만 하면 됩니다. XTaskQueueHandle을 다 사용했을 때, 일반적으로 게임이 끝날 때, XTaskQueueCloseHandle로 닫을 수 있습니다.
호출 샘플:

XTaskQueueHandle 수동으로 디스패치

XTaskQueueHandle의 작업 또는 완료 큐에 수동 큐 디스패치 모드를 사용한 경우 수동으로 디스패치해야 합니다. 작업 큐와 완료 큐가 모두 수동 디스패치로 설정된 XTaskQueueHandle이 다음과 같이 만들어졌다고 가정해 봅시다.
XTaskQueueDispatchMode::Manual로 할당된 작업을 디스패치하려면 XTaskQueueDispatch 함수를 호출합니다.
호출 샘플:
  • queue - 작업을 디스패치할 큐.
  • port - XTaskQueuePort 열거형의 인스턴스.
  • timeoutInMs - 밀리초 단위의 타임아웃에 대한 uint32_t.
XTaskQueuePort 열거형에서 정의된 두 가지 콜백 유형이 있습니다.

XTaskQueueDispatch를 호출해야 할 때

큐가 새 항목을 받았을 때를 확인하기 위해, XTaskQueueRegisterMonitor를 호출하여 이벤트 처리기를 설정하여 작업 또는 완료가 디스패치될 준비가 되었음을 코드에 알릴 수 있습니다.
XTaskQueueRegisterMonitor는 다음 매개변수를 사용합니다.
  • queue - 콜백을 제출하는 비동기 큐.
  • callbackContext - 제출 콜백에 전달되어야 하는 데이터에 대한 포인터.
  • callback - 새 콜백이 큐에 제출될 때 호출되는 함수.
  • token - 콜백을 제거하기 위해 나중에 XTaskQueueUnregisterMonitor를 호출할 때 사용되는 토큰.
예를 들어, 다음은 XTaskQueueRegisterMonitor에 대한 호출입니다.
해당하는 XTaskQueueMonitorCallback 콜백은 다음과 같이 구현될 수 있습니다.
그런 다음 백그라운드 스레드에서 이 조건 변수가 깨어날 때까지 수신 대기하고 XTaskQueueDispatch를 호출할 수 있습니다.

참고

마지막 수정일 2026년 8월 25일