API: Allow caching for output ports

This commit reverts 3d97601 ("More documentation in jack.h") partly.

The following call stack is used:
jack_port_get_buffer()
JackGraphManager::GetBuffer(jack_port_id_t, jack_nframes_t)
JackGraphManager::GetBuffer(jack_port_id_t)
JackPort::GetBuffer()

To call JackGraphManager::GetBuffer(jack_port_id_t, jack_nframes_t)
the object JackLibGlobals::fGlobals->fGraphManage is used. It is only
set in JackLibClient::Open(). Therefore it is not changed in the life
time of a JACK client.

In case port->fTied will be modified at runtime the returned audio
buffer would change. This variable can only be modified by the
deprecated jack_port_tie() function. Therefore as long as not calling
this deprecated function the audio buffer would not change.

The previous analyses is only valid for JACK audio output ports
(JackPortIsOutput). The creating JACK client can write to those
ports. For JACK audio input ports (JackPortIsInput) it is still not
allowed to cache the audio buffer address because for those ports the
returned audio buffer is depending on the port connections
(pipelining). The decision for the pipelining is done in
JackGraphManager::GetBuffer(jack_port_id_t, jack_nframes_t).

Change-Id: Ief1cd18d018d5e407876630c22254d87f3c55442
Signed-off-by: Timo Wischer <twischer@de.adit-jv.com>

common/jack/jack.h

@@ -760,15 +760,15 @@ int jack_port_unregister (jack_client_t *client, jack_port_t *port) JACK_OPTIONA
  * zero-filled. if there are multiple inbound connections, the data
  * will be mixed appropriately.
  *
- * FOR OUTPUT PORTS ONLY : DEPRECATED in Jack 2.0 !!
- * ---------------------------------------------------
+ * FOR OUTPUT PORTS ONLY
+ * ---------------------
  * You may cache the value returned, but only between calls to
  * your "blocksize" callback. For this reason alone, you should
  * either never cache the return value or ensure you have
  * a "blocksize" callback and be sure to invalidate the cached
  * address from there.
  *
- * Caching output ports is DEPRECATED in Jack 2.0, due to some new optimization (like "pipelining").
+ * Caching input ports is not allowed, due to some new optimization (like "pipelining").
  * Port buffers have to be retrieved in each callback for proper functioning.
  */
 void * jack_port_get_buffer (jack_port_t *port, jack_nframes_t) JACK_OPTIONAL_WEAK_EXPORT;

common/jack/types.h

@@ -468,13 +468,14 @@ enum JackPortFlags {
 
     /**
      * if JackPortIsInput is set, then the port can receive
-     * data.
+     * data from output ports. The creator of this port can
+     * read from it.
      */
     JackPortIsInput = 0x1,
 
     /**
-     * if JackPortIsOutput is set, then data can be read from
-     * the port.
+     * if JackPortIsOutput is set, then data can be forwarded to
+     * input ports. The creator of this port can write to it.
      */
     JackPortIsOutput = 0x2,