Skip to main content

Operaciones y notificaciones asincrónicas

Para las operaciones que pueden ser lentas o costosas desde el punto de vista computacional, el SDK de PlayFab Lobby y Matchmaking expone API asincrónicas. Las API asincrónicas le permiten iniciar operaciones costosas o lentas desde los subprocesos principales y sondear la finalización de esas operaciones en el subproceso que elija. Este mismo mecanismo de sondeo también se usa para entregar notificaciones asincrónicas de actualizaciones del SDK al código del título. Esta página ofrece una visión general de los patrones de API asincrónicas del SDK de PlayFab Lobby y Matchmaking y los procedimientos recomendados para programar con ellos.

Patrones básicos de API

Hay dos tipos de patrones de API asincrónicas que debe tener en cuenta en el SDK de PlayFab Lobby y Matchmaking:
  1. Operaciones asincrónicas
  2. Notificaciones asincrónicas

Operaciones asincrónicas

Usar las API asincrónicas del SDK es sencillo. El patrón general para iniciar y completar operaciones asincrónicas es el siguiente:
  1. Realice una llamada de método normal a la API asincrónica adecuada de su elección. Entre las operaciones asincrónicas comunes que probablemente utilizará se incluyen:
  2. Compruebe el valor devuelto HRESULT de la API con las macros SUCCEEDED() o FAILED(). Este valor devuelto de forma sincrónica le indicará si la operación se ha iniciado correctamente.
El valor devuelto sincrónico de una llamada a una API asincrónica NO le indica si la operación se ha completado correctamente o no. Para obtener más información sobre los errores sincrónicos frente a los asincrónicos, consulte la documentación de control de errores del SDK.
  1. Sondee la finalización de la operación asincrónica buscando el “cambio de estado de finalización” de la operación asociada proporcionado por PFMultiplayerStartProcessingLobbyStateChanges() o PFMultiplayerStartProcessingMatchmakingStateChanges. Un ejemplo del “cambio de estado de finalización” asociado a PFMultiplayerCreateAndJoinLobby() es PFLobbyCreateAndJoinLobbyCompletedStateChange. Puede encontrar información más detallada sobre qué son los “cambios de estado” y cómo funcionan en la sección Cambios de estado.
  2. Compruebe el valor result del cambio de estado de finalización para determinar si la operación se realizó correctamente o falló. Puede encontrar información más detallada sobre estos valores de error en la documentación de control de errores del SDK.

Notificaciones asincrónicas

Algunas características generarán notificaciones asincrónicas de cambios en el SDK de Lobby y Matchmaking. Entre las notificaciones comunes se incluyen:
  1. Notificaciones de actualización del lobby.
  2. Notificaciones de desconexión del lobby.
  3. Notificaciones de cambio de estado del ticket de matchmaking.
El SDK le proporcionará estas notificaciones asincrónicas como “cambios de estado” a través de PFMultiplayerStartProcessingLobbyStateChanges() y PFMultiplayerStartProcessingMatchmakingStateChanges. Puede encontrar información más detallada sobre qué son los “cambios de estado” y cómo funcionan en la sección Cambios de estado.

Cambios de estado

El modelo de API asincrónicas del SDK de Lobby y Matchmaking se basa en las estructuras PFLobbyStateChange y PFMatchmakingStateChange. Los PFLobbyStateChanges le notifican los cambios en el subsistema de lobby y los PFMatchmakingStateChanges le notifican los cambios en el subsistema de matchmaking. Estos “cambios de estado” son notificaciones asincrónicas de eventos del SDK. Estas notificaciones se ponen en cola internamente y usted las procesa llamando a PFMultiplayerStartProcessingLobbyStateChanges() y a PFMultiplayerStartProcessingMatchmakingStateChanges. Estas funciones devolverán todos los cambios de estado en cola (para su respectivo subsistema de API) como listas que puede recorrer y procesar individualmente. Cada cambio de estado tiene un campo stateChangeType correspondiente que se puede inspeccionar para determinar de qué cambio de estado específico se le está notificando. Una vez que sepa qué cambio de estado se le ha proporcionado, puede convertir la estructura genérica PFLobbyStateChange o PFMatchmakingStateChange en un tipo de estructura de cambio de estado más específico para inspeccionar los datos concretos de ese evento. Normalmente, el procesamiento de cambios de estado se implementa como una simple instrucción switch que delega cada cambio de estado en un controlador. Una vez que la lista de cambios de estado se ha procesado desde PFMultiplayerStartProcessingLobbyStateChanges o PFMultiplayerStartProcessingMatchmakingStateChanges, debe devolverse a PFMultiplayerFinishProcessingMatchmakingStateChanges() o a PFMultiplayerFinishProcessingMatchmakingStateChanges(), respectivamente.

Contextos de operaciones asincrónicas

Cada API asincrónica incluye un parámetro void* asyncContext. Este valor es un parámetro de paso directo que se establecerá en el cambio de estado de finalización asociado a esta llamada de API cuando lo proporcione PFMultiplayerStartProcessingLobbyStateChanges() o PFMultiplayerStartProcessingMatchmakingStateChanges(). Este valor le proporciona un mecanismo para adjuntar contextos arbitrarios del tamaño de un puntero a sus llamadas de API asincrónicas. Estos contextos se pueden usar en muchos escenarios, entre los que se incluyen:
  1. asociar datos específicos del título a una llamada del SDK
  2. vincular varias operaciones asincrónicas con un identificador compartido
Estos contextos asincrónicos no son necesarios para usar el SDK, pero pueden facilitar la escritura de cierta lógica del título.

Puesta en cola de operaciones

Con frecuencia, al trabajar con API asincrónicas, varias operaciones asincrónicas deben ejecutarse secuencialmente como parte de un flujo asincrónico más amplio. En el SDK de Lobby y Matchmaking, un ejemplo sería crear un lobby y enviar invitaciones a sus amigos para ese lobby. Serializado, este flujo tendría el siguiente aspecto:
  1. Llame a PFMultiplayerCreateAndJoinLobby() para crear un lobby de PlayFab y unirse a él.
  2. Espere a que PFLobbyCreateAndJoinLobbyCompletedStateChange refleje que el lobby se creó y se unió correctamente.
  3. Llame a PFLobbySendInvite() para cada amigo invitado.
  4. Espere a que PFLobbySendInviteCompletedStateChange refleje que la invitación se envió correctamente.
Para flujos y lógica de título más complicados, este patrón serializado puede ser apropiado. Sin embargo, para flujos más sencillos, el SDK proporciona una alternativa que pretende simplificar el código del título: Muchas API asincrónicas del SDK admiten la puesta en cola de operaciones dependientes antes de que una operación anterior se haya completado por completo. Siguiendo el ejemplo anterior, puede enviar una invitación para un lobby antes de haber visto que ese lobby se creó correctamente. En la práctica, la puesta en cola le permite agrupar una colección de operaciones asincrónicas, iniciarlas todas a la vez y consolidar el control de errores en un único punto de fallo.

Control del trabajo asincrónico

A veces es necesario que los títulos controlen dónde se realiza el trabajo asincrónico para evitar la contención de CPU entre las bibliotecas y las cargas de trabajo principales de CPU del título. El SDK de Lobby y Matchmaking le permite controlar cómo se ejecuta el trabajo asincrónico mediante Control de la afinidad de subprocesos

Control de la afinidad de subprocesos

De forma predeterminada, el trabajo asincrónico del SDK se realiza en subprocesos en segundo plano cuidadosamente controlados. Algunos títulos necesitan un control de grano grueso sobre dónde se programan estos subprocesos en segundo plano para evitar la contención de CPU. Para estos títulos, el SDK de Lobby y Matchmaking proporciona PFMultiplayerSetThreadAffinityMask(). En las plataformas compatibles, esto le permite limitar qué núcleos de CPU se usarán para los subprocesos en segundo plano del SDK. De esta forma, puede garantizar que determinados núcleos queden reservados para sus propias cargas de trabajo de CPU sin ninguna contención.
Última modificación el 28 de agosto de 2026