More documentation

git-svn-id: http://subversion.jackaudio.org/jack/jack2/trunk/jackmp@2037 0c269be4-1314-0410-8aa9-9f06e86f4224

common/jack/jack.h

@@ -179,31 +179,51 @@ extern "C"
      * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000
      * for more information.
      *
-     * @return 0 on success, otherwise a non-zero error code, causing JACK
-     * to remove that client from the process() graph.
+     * @return 0 on success, otherwise a non-zero error code.
      */
     int jack_set_process_callback (jack_client_t *client,
                                    JackProcessCallback process_callback,
                                    void *arg);
+    /**
+	* \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
+	*  NEW JACK CLIENTS.
+    *
+    * It should be replace by use of @ jack_thread_wait and @ jack_cycle_wait functions.
+	*
+	*/
+	jack_nframes_t jack_thread_wait (jack_client_t*, int status);
+	
 	/**
-	* Block until this JACK client should process data.
-	* 
-	* The @a status argument typically indicates the result
-	* of some recent data processing.
+	* Wait until this JACK client should process data.
 	* 
 	* @param client - pointer to a JACK client structure
-	* @param status - if non-zero, calling thread should exit
 	*
 	* @return the number of frames of data to process
 	*/
-	jack_nframes_t jack_thread_wait (jack_client_t*, int status);
-	
-	// New experimental alternate threading model
 	jack_nframes_t jack_cycle_wait (jack_client_t* client);
 	
+    /**
+	* Signal next clients in the graph.
+	* 
+	* @param client - pointer to a JACK client structure
+	* @param status - if non-zero, calling thread should exit
+	*/
 	void jack_cycle_signal (jack_client_t* client, int status);
 	
-	int jack_set_process_thread(jack_client_t* client, JackThreadCallback fun, void *arg);
+    /**
+     * Tell the Jack server to call @a thread_callback in the RT thread.
+     * Typical use are in conjunction with @a jack_cycle_wait and @ jack_cycle_signal functions.
+     * The code in the supplied function must be suitable for real-time
+     * execution.  That means that it cannot call functions that might
+     * block for a long time.  This includes malloc, free, printf,
+     * pthread_mutex_lock, sleep, wait, poll, select, pthread_join,
+     * pthread_cond_wait, etc, etc.  See
+     * http://jackit.sourceforge.net/docs/design/design.html#SECTION00411000000000000000
+     * for more information.
+     *
+     * @return 0 on success, otherwise a non-zero error code.
+    */
+	int jack_set_process_thread(jack_client_t* client, JackThreadCallback thread_callback, void *arg);
 	
     /**
      * Tell JACK to call @a thread_init_callback once just after

common/jack/types.h

@@ -111,6 +111,15 @@ typedef uint32_t jack_port_id_t;
  */
 typedef int (*JackProcessCallback)(jack_nframes_t nframes, void *arg);
 
+/**
+ * Prototype for the client thread routine called 
+ * by the engine when the client is inserted in the graph.
+ *
+ * @param arg pointer to a client supplied structure
+ *
+ */
+typedef void *(*JackThreadCallback)(void* arg);
+
 /**
  * Prototype for the client supplied function that is called 
  * once after the creation of the thread in which other
@@ -215,8 +224,6 @@ typedef void (*JackPortConnectCallback)(jack_port_id_t a, jack_port_id_t b, int
 typedef void (*JackFreewheelCallback)(int starting, void *arg);
 
 
-typedef void *(*JackThreadCallback)(void* arg);
-
 /**
  * Used for the type argument of jack_port_register() for default
  * audio ports and midi ports.