Automatic Throttling of General Requests
The Vivox SDK is well-optimized to handle many requests quickly and consistently, so client-side throttling or request rate limiting is rare in a well-written integration. The best practice is to issue no more than 15 SDK requests per second, excluding the following:
- Requests to set 3D position in a Positional channel.
- Requests to get or set audio devices or to globally adjust audio device muting/volume (commonly used in voice chat settings menu UI, or for push-to-talk).
- Requests which adjust session_group transmission to all, none, or a specific channel (sometimes used for push-to-talk).
- Requests which have "local" in the name (such as
req_session_set_local_render_volume).
The above exceptions can be sent more frequently without being subject to rate limiting. The rules controlling request throttling are a bit more tolerant than this but are too complex to list out fully.
Recommended Rate of 3D Positional Update Requests
As a best practice for 3D positional updates, we recommend limiting request calls and caching your position and orientation, so updates stop when your character isn't moving. We suggest starting at 10-15 requests per second to set 3D position and not going much higher. Updating once per frame or game tick—even with caching—is not recommended, as excessive updates can cause delays in processing other requests.
Frequent updates do help since the new values are used in calculations immediately. However, there are diminishing returns in human perception, so while higher accuracy is "better", 10-15 is a good level for most integrations in our experience. VR applications with real-time head tracking might consider testing a slightly higher rate (there's no throttling/hard cap), but typical 1st and 3rd person games should be good at that level.
How to Check the Number of Outstanding Requests
Core SDK
When calling vx_issue_request3(), use the out parameter request_count to get a count of the current request queue depth whenever a request is issued. An application can use this value to monitor the queue depth and determine if the application is issuing requests at an unacceptable rate.
Unreal SDK
Whenever a Vivox Unreal API call results in a Vivox request being issued internally: if the queue depth at that time exceeds 10, then the plugin will print a Warning level log message indicating the number of outstanding requests.
Unity SDK
There is currently no way to know the number of outstanding Vivox requests using the Unity SDK.
General Tips to Avoid Runaway Request Queue Depth
In addition to the specific recommendations above for 3D positional updates, be especially mindful of any Vivox requests made in a loop, such as with retry logic when receiving a non-zero status code in an event, response, or callback. Retries should not be instant, nor infinite, and in some cases, failing calls should not be retried at all.
Examples of non-zero statuses which should have a user-initiated retry or exponential backoff retry (which eventually gives up) include VxErrorRtpTimeout and VxErrorConnectionTerminated. Network-related errors are the most common class of error which has a chance of succeeding on retry: retrying an operation after receiving and error of this type is acceptable so long as reasonable precautions are taken not to flood the server with requests.
Examples of non-zero statuses resulting from a programming error—which should not be retried—include VxErrorInvalidArgument and VxErrorHandleTaken. These and similar errors should be caught and fixed during development. Note that some non-zero statuses can be regarded as a success depending on the context, such as when VxErrorTargetObjectDoesNotExist is received when trying to leave a channel you're not currently joined to.