Pa_SelectHostApis to specify which host APIs will be initialized at startup

[PortAudio-admin]

Issue created by @RossBencina

Change host API Ids to a bit mask and provide a function

Pa_SelectHostApis( hostApis, capacity, count)

which can be called prior to Pa_Initialize() to determine which APIs will be initialized.

This could avoid initializing unwanted APIs (and all sorts of problems on Windows with buggy drivers when trying to init DirectSound and ASIO and MME all for the same app.

Earlier versions of this proposal proposed Pa_SetHostApiInitializationMask() with a bitmask to specify which host apis to initialize.

A prototype implementation is now available on the git "ticket-10-select-host-apis" branch. See the documentation in portaudio.h for details. See comments below for notes on the evolution of the prototype.

https://app.assembla.com/spaces/portaudio/git/compare/portaudio:ticket-10-select-host-apis...portaudio:master

[PortAudio-admin]

Comment by @RossBencina

Updated after marking #13 as a duplicate.

Note that making host API Ids a bit-mask rather than a sequential enumeration would limit us to 31 host apis in the future, but I sincerely hope we will never get to the point of supporting 31 host APIs anyway. Note that because some API functions return a HostAPI ID or a -ve error code, we can't use the high bit for an API id.

The default mask should be set so that if Pa_SetHostApiInitializationMask() isn't called, all available APIs are initialized.

[PortAudio-admin]

Comment by @RossBencina

Another option is for Pa_SetHostApiInitializationMask() to take an array of host API type ids. That would allow initialization order/defaults to also be selected. We may also want to consider an API that supports both masking (disabling) certain APIs, and one that supports enabling only a set of APIs. Another thing that might be needed is a way to query which APIs are available/compiled in.

[PortAudio-admin]

Comment by @RossBencina

TRAC migration: propagating ticket status from TRAC

[PortAudio-admin]

Comment by @RossBencina

I've comitted a prototype implementation to the ticket-10-select-host-apis branch. Here's the commit message:

An implementation of runtime host API selection (see ticket #10). See the changes to portaudio.h for documentation for the API. Note that unlike other proposals, this version of the interface allows the client to specify the order of host API initialization. The API is excercised by patest_select_hostapis.c. To reviewers: please verify that the implementation of Pa_SelectHostApis, Pa_GetSelectedHostApis and Pa_GetAvailableHostApis in pa_front.c matches the documentation in portaudio.h

b8d4bd6

[PortAudio-admin]

Comment by @RossBencina

Notes on the current API design in the ticket-10-select-host-apis branch:

I chose not to use a bitmask because that wouldn't allow the initialization order to be specified. It would have also lead to either (1) a messy API (mapping type ids to a bitmask) or (2) having to make a breaking change to make type ids use unique bits.

I added a function to query the available host APIs, as per a request on the mailing list (seems reasonable), and a function to query which host APIs are selected (for completeness).

Note that Pa_SelectHostApis will fail if you specify a host API that is not in the available host APIs list.

[PortAudio-admin]

Comment by @RossBencina

Daniel Schrmann provided this feedback on the mailing list:

I have skimmed to the diffs and have some comments:

• A call to Pa_SelectHostApis() should be rejected after calling Pa_Initialize() and before Pa_Terminate();
• The might be a future confusion between PaHostApiIndex and the order chosen in Pa_SelectHostApis(). Do they match? I think they should if possible.
• Instead of using paHostApiInitializers, Pa_GetAvailableHostApis() should call an IsAvailable() function of the API implementation. This would allow to pass the decision which API should be used to the user, without knowing anything of it in the client application.
  IsAvailable() can return false if a required DLL is missing, or something else which can be checked without actually initialize the HostAPI.
• MAX_HOST_API_COUNT could be provided by PA_GetMaxHostApiCount()

Kind regards,

Daniel

[PortAudio-admin]

Comment by @RossBencina

Changes 3 September 9039daf..90fa011

• f13a626 calling Pa_SelectHostApis now returns an error if it is called while PA is initialized.
• 196f025 (and later) added comments that we need to review the name of Pa_GetAvailableHostApis to reflect the fact that this is just the "compiled in" host apis not the host apis present on the system.
• a3d9f6c document that initialization order does not predictably determine host api indexes
• add Pa_GetAvailableHostApisCount()

The latest diff vs master can always be reviewed here:

https://app.assembla.com/spaces/portaudio/git/compare/portaudio:ticket-10-select-host-apis...portaudio:master

[PortAudio-admin]

Comment by @RossBencina

From my point of view, what is needed now is further code review and testing. The only outstanding issue is to select a better name than "available" for Pa_GetAvailableHostApis and Pa_GetAvailableHostApisCount. If anyone has any other comments please let us know.

[PortAudio-admin]

Comment by @RossBencina

Added #253 to cover detecting installed host apis at runtime