Changes between Version 2 and Version 3 of develop

Timestamp:

2013-04-13 12:07:13 (12 years ago)

Author:

futzle

Comment:

--

develop

@@ -37 +37 @@
 After the '''SUBSCRIBE''' request succeeds, the plugin will have a subscription identifier (SID) ''sid'', and a duration in seconds ''timeout''.  For the next ''timeout'' seconds, the UPnP device will send '''NOTIFY''' messages to the callback URL.
 
-The plugin has an action ''VariableChanged'' in service ''pluginServiceId'' which accepts two parameters: ''valueParam'' (the new value of the varable), and ''sidParam'' (the subscription identifier).  The plugin wants this action to be invoked by the proxy every time that ''UPnPVariable'' changes.
+The plugin has an action ''!VariableChanged'' in service ''pluginServiceId'' which accepts two parameters: ''valueParam'' (the new value of the varable), and ''sidParam'' (the subscription identifier).  The plugin wants this action to be invoked by the proxy every time that ''UPnPVariable'' changes.
 
 To register the subscription with the proxy, perform an HTTP '''PUT''' to /upnp/event/''sid'':
@@ -53 +53 @@
   method = "PUT",
   headers = {
-    ["Content-Type"] = "text/html",
+    ["Content-Type"] = "text/xml",
     ["Content-Length"] = proxyRequestBody:len(),
   },
@@ -68 +68 @@
 }}}
 
-The proxy will soon receive (or may have already received) the initial UPnP '''NOTIFY''' (with sequence 0), and will invoke the ''VariableChanged'' action on the plugin.
+The proxy will soon receive (or may have already received) the initial UPnP '''NOTIFY''' (with sequence 0), and will invoke the ''!VariableChanged'' action on the plugin.
 
 == Receiving an event notification from the proxy ==
 
-The plugin should have an action ''VariableChanged'', matching the ''serviceId'' and ''action'' parameters supplied in the previous section's sample code.  In the
+The plugin should have an action ''!VariableChanged'', matching the ''serviceId'' and ''action'' parameters supplied in the previous section's sample code.  In the
 
 {{{
@@ -120 +120 @@
 == Avoiding deadlocks ==
 
-TODO
+The proxy runs in a single thread.  Consequently it is vital that plugins do not delay it when actions are invoked by the proxy, because it will prevent other plugins and UPnP devices from contacting the proxy.
+
+To minimize the likelihood of delays, plugins should restrict their actions to a minimum during actions such as ''!VariableChanged''.  The plugin should liberally use luup.call_delay() for anything that may block or take significant time to run.
+
+Because the plugin makes HTTP requests to the proxy and the proxy makes action calls to the plugin, there is a risk of deadlock.  To minimize this, the proxy will time out and retry after a random period of time from 1 to 5 seconds, up to a maximum of three times.  If the action still cannot be delivered then it is discarded.  It is a good idea for the plugin to do the same, using retry counters and luup.call_delay() to compartmentalize each invocation and allow the proxy to contact the plugin as soon as possible.