Callback delivery
Understand how the package reads the callback queue and delivers callbacks to your code, including when the handlers run and how long the callback data remains valid.
The Steamworks API provides two different types of asynchronous results. The Steamworks API package handles each type differently:
- Callbacks: These are broadcast events, for example, a change in a friend's online state. The Steamworks API queues each callback as a message, regardless of its cause. Subscribe to a callback to receive these events. The package reads the queue and passes each callback to a handler, which is a method that you pass to
SteamCallbacks.Subscribe. For more information, refer to Callbacks (Valve). - Call results: These are responses to specific API requests, for example, the number of users currently using your application. Await a call result to receive the response to your request. For more information, refer to CallResults (Valve).
By default, the package processes the callback queue automatically, so you don't need to call a method in your update loop to run callbacks. When SteamAPI.Init or GameServer.InitEx succeeds, the package starts a background thread that reads the callback queue at a fixed interval, called the poll interval. The package then delivers each message to your handlers on the main thread, so you can call Unity APIs directly from a handler. For more information, refer to Choose a callback dispatch mode.
To subscribe to callbacks, refer to Handle callbacks and call results.
Delivery timing
A handler runs within one poll interval and up to one frame after the message reaches the callback queue. To change the poll interval, set SteamCallbacks.PollIntervalMilliseconds. The default value is 32 ms and the minimum is 1 ms.
Handler thread
The package uses Unity's synchronization context to run handlers on the main thread. If no synchronization context is available, such as when you initialize the Steamworks API on a worker thread, handlers run on the background thread instead. For more information, refer to SynchronizationContext (Microsoft).
Callback data lifetime
The data in a SteamCallbackMessage is valid only while the handler runs. This applies when you receive a message through SteamCallbacks.OnCallback or SteamCallbacks.OnGameServerCallback. To use the data after the handler finishes running, copy it first. Handlers that you add with SteamCallbacks.Subscribe<T> receive their own copy of the callback data, so you can use it after the handler finishes running.