Changeset 41 for pa_proposals/trunk

Timestamp:

10/20/02 18:42:51 (6 years ago)

Author:

rossbencina

Message:

- updated to reflect that Pa_Initialize/Pa_Terminate are now reference counted and must be paired correctly

Files:

• pa_proposals/trunk/012-AdditionalTerminateBehavior.html (modified) (5 diffs)

pa_proposals/trunk/012-AdditionalTerminateBehavior.html

@@ -18 +18 @@
 <P><A href="index.html">Enhancement Proposals Index</A>,
 <A href="http://www.portaudio.com/">PortAudio Home Page</A></P>
-<P>Updated: July 23, 2002 </P>
+<P>Updated: October 21, 2002 </P>
 
 <H4>Status</H4>
@@ -27 +27 @@
 
 <P>
-Some host APIs (eg ASIO, MME and DirectSound under Windows NT) can require a reboot to free devices when they are not closed properly (due to a program not calling Pa_Close() either in error, or due to a crash.) As a quality of implementation issue PortAudio should seek to avoid such circumstances.
+Some host APIs (eg ASIO, MME and DirectSound under Windows NT) can require a reboot to free devices when they are not closed properly due to a program not calling Pa_CloseStream() either in error, or due to a crash. As a quality of implementation issue PortAudio should seek to avoid such circumstances.
 </P>
 
 <H4>Proposal</H4>
 
-<P>The definition of Pa_Terminate() should be extended as follows:</P>
+<P>
+To improve the chances that all streams are closed before an application using PortAudio exits, PortAudio will keep track of all open streams and automatically close any that are still open when Pa_Terminate() is called. If a process calls Pa_Initialise()/Pa_Terminate() in two or more separate subsystems, the first call to Pa_Terminate() must not close streams beloning to another subsystem. Therefore, PortAudio will require calls to Pa_Initialize() to be correctly matched with calls to Pa_Terminate(), and will only close  open streams when the final call to Pa_Terminate() is made for which it has registered a matching Pa_Initialize().
+</P>
+
+
+<P>The definition of Pa_Initialize() will be extended as follows:</P>
 
 <PRE>
-/*
-    Pa_Terminate() is the library termination function - call this after 
-    using the library. This function deallocates all resources allocated 
-    by PortAudio since it was initializied using Pa_Initialize(). Any open 
-    PortAudioStreams are closed.
+/** Library initialization function - call this before using PortAudio.
+ This function initialises internal data structures and prepares underlying
+ host APIs for use. This function MUST be called before using any other
+ PortAudio API functions.
 
-    Pa_Terminate() MUST be called before exiting a program which 
-    uses PortAudio. Failure to do so may result in serious resource 
-    leaks, such as audio devices not being available until the next reboot.
+ If Pa_Initialize() is called multiple times, each call must be matched with
+ a corresponding call to Pa_Terminate(). Pairs of calls to
+ Pa_Initialize()/Pa_Terminate() may overlap, and are not requireed to be fully
+ nested.
+*/
+PaError Pa_Initialize( void );
+</PRE>
+
+
+<P>The definition of Pa_Terminate() will be extended as follows:</P>
+
+<PRE>
+/** Library termination function - call this when finished using PortAudio.
+ This function deallocates all resources allocated by PortAudio since it was
+ initializied by a call to Pa_Initialize(). In cases where Pa_Initialize() has
+ been called multiple times, each call must be matched with a corresponding call
+ to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically
+ close any PortAudio streams that are still open.
+
+ Pa_Terminate() MUST be called before exiting a program which uses PortAudio.
+ Failure to do so may result in serious resource leaks, such as audio devices
+ not being available until the next reboot.
 */
 PaError Pa_Terminate( void );
@@ -51 +74 @@
 
 <P>
-One possible implementation strategy would be to add a "next" member to the internal stream data structure thus making it a linked list node, which could be linked into a list of all open streams.
+One possible implementation strategy would be to add a "next" member to the internal stream data structure thus making it a linked list node, which could be linked into a list of all open streams. It has been noted that using a doubly linked list would make closing streams a constant-time operation.
 </P>
 
@@ -61 +84 @@
 
 <P>
-There has been some discussion about the behavior of nesting multiple calls to Pa_Initialize() and Pa_Terminate() - there is no intention of changing the current behaviour, which is that PortAudio has two states: "Initialized" and "Uninitialized" - in the Initialized state, Pa_Initialize() does nothing and returns an error, in the Uninitialized state Pa_Terminate() does nothing and returns an error.
-[META]This assertion needs to be checked against the v19-devel implementation.[/META]
+The original (V18 and previous) behavior of calling Pa_Initialize() / Pa_Terminate() multiple times was that the first call to Pa_Initialize() would initialize the library, and the first call to Pa_Terminate() would uninitialize it. For some time it was considered desirable to retain this behavior. However, as noted above, this is not the best behavior for clients who initialize PortAudio multiple times from independent subsystems - especially when Pa_Terminate() can close all open streams. It was concluded that it was best to require matched calls to Pa_Initialize()/Pa_Terminate() as described in this proposal.
 </P>
 
@@ -68 +90 @@
 
 <P>
-This proposal changes the termination behaviour of PortAudio to reduce the likelihood of resource leaks.</P>
+This proposal changes the termination behaviour of PortAudio to reduce the likelihood of resource leaks.
+</P>
 
 <P>