diff --git a/src/client/pv/pvAccess.h b/src/client/pv/pvAccess.h
index d04c390..edd1058 100644
--- a/src/client/pv/pvAccess.h
+++ b/src/client/pv/pvAccess.h
@@ -158,7 +158,13 @@ struct epicsShareClass ChannelBaseRequester : virtual public epics::pvData::Requ
*
* (re)connection is notified through a sub-class *Connect() method.
*
- * @param destroy true for final disconnect (shutdown).
+ * Any in-progress get()/put()/request()/start() is implicitly cancel()'d or stop()'d
+ * before this method is called.
+ *
+ * Ownership of any PVStructures passed to completion callbacks (eg. ChannelGetRequester::getDone() )
+ * is returned the operation
+ *
+ * @param destroy true for final disconnect.
*/
virtual void channelDisconnect(bool destroy) {}
};
@@ -244,8 +250,12 @@ public:
/**
* put to the remote array.
+ *
+ * Ownership of the PVArray is transferred to the ChannelArray until ChannelArrayRequester::putArrayDone()
+ * or ChannelArrayRequester::channelDisconnect() is called.
+ *
* @param putArray array to put.
- * @param offset The offset in the remote array, i.e. the PVArray returned by ChannelArrayRequester.channelArrayConnect.
+ * @param offset The offset in the remote array, i.e. the PVArray returned by ChannelArrayRequester::channelArrayConnect.
* @param count The number of elements to put, 0 means "entire array".
* @param stride 1 means all the elements from offset to count, 2 means every other, 3 means every third, etc.
*/
@@ -255,7 +265,11 @@ public:
/**
* get from the remote array.
- * @param offset The offset in the remote array, i.e. the PVArray returned by ChannelArrayRequester.channelArrayConnect.
+ *
+ * Ownership of the PVArray previously passed to ChannelArrayRequester::getArrayDone()
+ * is returned to the ChannelArray from the ChannelArrayRequester.
+ *
+ * @param offset The offset in the remote array, i.e. the PVArray returned by ChannelArrayRequester::channelArrayConnect.
* @param count The number of elements to get, 0 means "till the end of an array".
* @param stride 1 means all the elements from offset to count, 2 means every other, 3 means every third, etc.
*/
@@ -288,8 +302,8 @@ public:
* May call putArray(), getArray(), getLength(), or setLength() to execute.
*
* @param status Completion status.
- * @param channelArray The channelArray interface or null if the request failed.
- * @param pvArray The PVArray that holds the data or null if the request failed.
+ * @param channelArray The channelArray interface or nullptr if the request failed.
+ * @param pvArray The PVArray that holds the data or nullptr if the request failed.
*/
virtual void channelArrayConnect(
const epics::pvData::Status& status,
@@ -298,6 +312,9 @@ public:
/**
* The request is done. This is always called with no locks held.
+ *
+ * Ownership of PVArray passed to ChannelArray::putArray() returns to ChannelArrayRequester
+ *
* @param status Completion status.
* @param channelArray The channelArray interface.
*/
@@ -307,9 +324,13 @@ public:
/**
* The request is done. This is always called with no locks held.
+ *
+ * Ownership of the PVArray is transfered to the ChannelArrayRequester until
+ * a subsequent call to ChannelArray::getArray() or ChannelArrayRequester::channelDisconnect().
+ *
* @param status Completion status.
* @param channelArray The channelArray interface.
- * @param pvArray The PVArray that holds the data or null if the request failed.
+ * @param pvArray The PVArray that holds the data or nullptr if the request failed.
*/
virtual void getArrayDone(
const epics::pvData::Status& status,
@@ -403,7 +424,11 @@ public:
/**
* Get data from the channel.
- * Completion status is reported by calling ChannelGetRequester.getDone() callback.
+ *
+ * Ownership of the PVStructure passed to ChannelGetRequester::getDone() is
+ * returned to the ChannelGet.
+ *
+ * Completion status is reported by calling ChannelGetRequester::getDone() callback.
*/
virtual void get() = 0;
};
@@ -422,8 +447,8 @@ public:
/**
* The client and server have both completed the createChannelGet request.
* @param status Completion status.
- * @param channelGet The channelGet interface or null if the request failed.
- * @param structure The introspection interface of requested get structure or null if the request failed.
+ * @param channelGet The channelGet interface or nullptr if the request failed.
+ * @param structure The introspection interface of requested get structure or nullptr if the request failed.
*/
virtual void channelGetConnect(
const epics::pvData::Status& status,
@@ -432,10 +457,14 @@ public:
/**
* The request is done. This is always called with no locks held.
+ *
+ * Ownership of the PVStructure is passed to the ChannelGetRequester until a subsequent call to
+ * ChannelGet::get() or ChannelGetRequester::channelDisconnect()
+ *
* @param status Completion status.
* @param channelGet The channelGet interface.
- * @param pvStructure The PVStructure that holds the data or null if the request failed.
- * @param bitSet The bitSet for that shows what data has changed or null if the request failed.
+ * @param pvStructure The PVStructure that holds the data or nullptr if the request failed.
+ * @param bitSet The bitSet for that shows what data has changed or nullptr if the request failed.
*/
virtual void getDone(
const epics::pvData::Status& status,
@@ -476,7 +505,7 @@ public:
/**
* The client and server have both completed the createChannelProcess request.
* @param status Completion status.
- * @param channelProcess The channelProcess interface or null if the client could not become
+ * @param channelProcess The channelProcess interface or nullptr if the client could not become
* the record processor.
*/
virtual void channelProcessConnect(
@@ -506,7 +535,13 @@ public:
/**
* Put data to a channel.
- * Completion status is reported by calling ChannelPutRequester.putDone() callback.
+ *
+ * Completion status is reported by calling ChannelPutRequester::putDone()
+ *
+ * Ownership of the PVStructure is transfered to the ChannelPut until
+ * ChannelPutRequester::putDone() or ChannelPutRequester::channelDisconnect()
+ * is called.
+ *
* @param pvPutStructure The PVStructure that holds the putData.
* @param putBitSet putPVStructure bit-set (selects what fields to put).
*/
@@ -516,6 +551,8 @@ public:
/**
* Get the current data.
+ *
+ * Ownership transfer as with ChannelGet::get()
*/
virtual void get() = 0;
@@ -535,7 +572,7 @@ public:
* The client and server have both processed the createChannelPut request.
* @param status Completion status.
* @param channelPut The channelPut interface or null if the request failed.
- * @param structure The introspection interface of requested put/get structure or null if the request failed.
+ * @param structure The introspection interface of requested put/get structure or nullptr if the request failed.
*/
virtual void channelPutConnect(
const epics::pvData::Status& status,
@@ -553,10 +590,13 @@ public:
/**
* The get request is done. This is always called with no locks held.
+ *
+ * Ownership transfer as with ChannelGetRequester::getDone()
+ *
* @param status Completion status.
* @param channelPut The channelPut interface.
- * @param pvStructure The PVStructure that holds the data or null if the request failed.
- * @param bitSet The bitSet for that shows what data has changed or null if the request failed.
+ * @param pvStructure The PVStructure that holds the data or nullptr if the request failed.
+ * @param bitSet The bitSet for that shows what data has changed or nullptr if the request failed.
*/
virtual void getDone(
const epics::pvData::Status& status,
@@ -616,8 +656,8 @@ public:
* The client and server have both completed the createChannelPutGet request.
* @param status Completion status.
* @param channelPutGet The channelPutGet interface or null if the request failed.
- * @param putStructure The put structure introspection data or null if the request failed.
- * @param getStructure The get structure introspection data or null if the request failed.
+ * @param putStructure The put structure introspection data or nullptr if the request failed.
+ * @param getStructure The get structure introspection data or nullptr if the request failed.
*/
virtual void channelPutGetConnect(
const epics::pvData::Status& status,
@@ -629,8 +669,8 @@ public:
* The putGet request is done. This is always called with no locks held.
* @param status Completion status.
* @param channelPutGet The channelPutGet interface.
- * @param pvGetStructure The PVStructure that holds the getData or null if the request failed.
- * @param getBitSet getPVStructure changed bit-set or null if the request failed.
+ * @param pvGetStructure The PVStructure that holds the getData or nullptr if the request failed.
+ * @param getBitSet getPVStructure changed bit-set or nullptr if the request failed.
*/
virtual void putGetDone(
const epics::pvData::Status& status,
@@ -642,8 +682,8 @@ public:
* The getPut request is done. This is always called with no locks held.
* @param status Completion status.
* @param channelPutGet The channelPutGet interface.
- * @param pvPutStructure The PVStructure that holds the putData or null if the request failed.
- * @param putBitSet putPVStructure changed bit-set or null if the request failed.
+ * @param pvPutStructure The PVStructure that holds the putData or nullptr if the request failed.
+ * @param putBitSet putPVStructure changed bit-set or nullptr if the request failed.
*/
virtual void getPutDone(
const epics::pvData::Status& status,
@@ -655,8 +695,8 @@ public:
* The getGet request is done. This is always called with no locks held.
* @param status Completion status.
* @param channelPutGet The channelPutGet interface.
- * @param pvGetStructure The PVStructure that holds the getData or null if the request failed.
- * @param getBitSet getPVStructure changed bit-set or null if the request failed.
+ * @param pvGetStructure The PVStructure that holds the getData or nullptr if the request failed.
+ * @param getBitSet getPVStructure changed bit-set or nullptr if the request failed.
*/
virtual void getGetDone(
const epics::pvData::Status& status,