From 91ce807e8beedc3d6449cee4209ae1b14d4d0be1 Mon Sep 17 00:00:00 2001
From: Benjamin Franksen <Ben Franksen benjamin.franksen@helmholtz-berlin.de>
Date: Wed, 11 Apr 2018 12:58:28 +0200
Subject: [PATCH] Fix for lp: #1751380

Add warnings about possible deadlock to the docs for ca_clear_channel,
ca_clear_subscription, and ca_context_destroy.
---
 src/ca/CAref.html | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/ca/CAref.html b/src/ca/CAref.html
index 13bcd795f..0651b2c26 100644
--- a/src/ca/CAref.html
+++ b/src/ca/CAref.html
@@ -2674,6 +2674,14 @@ automatically released by the system when the process exits and
 vxWorks or RTEMS no cleanup occurs unless the application calls
 <code>ca_context_destroy()</code>.</p>
 
+<p>Note: This operation blocks until any user callbacks for any channel
+created in the current context have run to completion. If callbacks take a
+lock (mutex) then it is the user's responsibility to ensure that this lock
+is not held when <code>ca_clear_context()</code> is called, otherwise a
+deadlock may ensue. (See also <code><a
+href="#ca_clear_channel">ca_clear_channel</a>()</code> and <code><a
+href="#ca_clear_event">ca_clear_subscription</a>()</code>.)</p>
+
 <h4>Returns</h4>
 
 <p>ECA_NORMAL - Normal successful completion</p>
@@ -2819,6 +2827,12 @@ efficiently sent over the network in one message.</p>
 clearing a channel does shutdown and reclaim any channel state change event
 subscriptions (monitors) registered with the channel.</p>
 
+<p>Note: This operation blocks until any user callbacks for this channel
+have run to completion. If callbacks take a lock (mutex) then it is the
+user's responsibility to ensure that this lock is not held when
+<code>ca_clear_channel()</code> is called, otherwise a deadlock may ensue.
+(See also <code><a href="#ca_clear_event">ca_clear_subscription</a>()</code>.)</p>
+
 <h4>Arguments</h4>
 <dl>
   <dt><code>CHID</code></dt>
@@ -3200,6 +3214,13 @@ and not forwarded to the server until one of <code>ca_flush_io()</code>, <code>c
 <code>ca_pend_event()</code>, or <code>ca_sg_block()</code> are called. This allows several requests to be
 efficiently sent together in one message.</p>
 
+<p>Note: This operation blocks until any user callbacks for this channel
+have run to completion. If callbacks take a lock (mutex) then it is the
+user's responsibility to ensure that this lock is not held when
+<code>ca_clear_subscription()</code> is called, otherwise a deadlock may
+ensue. (See also <code><a
+href="#ca_clear_channel">ca_clear_channel</a>()</code>.)</p>
+
 <h4>Arguments</h4>
 <dl>
   <dt>EVID</dt>