Merge pull request #2286 from ControlSystemStudio/pva_beacons

PVA name search cleanup & doc

Author: kasemir

core/pva/README.md

@@ -130,7 +130,15 @@ the tools provided by EPICS base:
     pvget demo
     pvmonitor demo
 
+Protocol Test Tools
+-------------------
 
+`pvasearchmonitor` or invoking the phoebus command line with `-main org.epics.pva.server.PVASearchMonitorMain`
+starts a tool that periodically lists received search requests.
+
+`pvaclient beacons` or invoking the phoebus command line with `-main org.epics.pva.client.PVAClientMain beacons`
+starts a tool that lists received beacons.
+ 
 
 API Documentation
 -----------------
@@ -146,10 +154,15 @@ PVA Client:
 
  * PVA Server list
  * Maintains pool of PVs
- * Registers new PVs with ChannelSearch
- * ChannelSearch: Exponential backup to ~30 seconds
+ * Registers new PVs with ChannelSearch, which supports UDP and TCP searches,
+   i.e. search via broadcast/multicast/unicase or via a name server
+ * ChannelSearch: Linear backup of 1, 2, 3, .. seconds between repeated 
+   searches, setting to searching once every 30 seconds after about 7 minutes
+ * Clients monitor beacons. If the search has settled to once every 30 seconds,
+   any new beacon restarts the linear backup to facilitate faster reconnect.
+   Beacons are not required for a reconnect, but they may accelerate it
  * Forward unicast searches to local multicast group
- * Creates TCPHandler when channel found.
+ * Creates TCPHandler when channel found
  * Support "anonymous" or "ca"
    (with user from "user.name" property and host from InetAddress.getLocalHost().getHostName())
  * Echo test when no new data for a while,
@@ -184,4 +197,5 @@ PVA Server:
 TODO:
 
  * Testing
+ * Implement beacons in server
  * Handle fixed size or bounded arrays?

core/pva/src/main/java/org/epics/pva/client/ChannelSearch.java

@@ -98,8 +98,20 @@ private class SearchedChannel
         }
     }
 
+    // SearchedChannels are tracked in two data structures
+    //
+    // - searched_channels (concurrent)
+    //   Fast lookup of channel by ID,
+    //   efficient `computeIfAbsent(cid, ..` mechanism for creating
+    //   at most one SearchedChannel per CID.
+    //   Allows checking if a channel is indeed searched,
+    //   and locating the channel for a search reply.
+    //
+    //  - search_buckets (need to SYNC)
+    //   Efficiently schedule the search messages for all channels
+    //   up to MAX_SEARCH_PERIOD.
+
     /**  Map of searched channels by channel ID */
-    // TODO Remove, just use search_buckets?
     private ConcurrentHashMap<Integer, SearchedChannel> searched_channels = new ConcurrentHashMap<>();
 
     /** Search buckets
@@ -241,12 +253,10 @@ public PVAChannel unregister(final int channel_id)
         if (searched != null)
         {
             logger.log(Level.FINE, () -> "Unregister search for " + searched.channel.getName() + " " + channel_id);
-
-            synchronized (search_buckets)
-            {
-                for (LinkedList<SearchedChannel> bucket : search_buckets)
-                    bucket.remove(searched);
-            }
+            // NOT removing `searched` from all `search_buckets`.
+            // Removal would be a slow, linear operation.
+            // `runSearches()` will drop the channel from `search_buckets`
+            // because it's no longer listed in `searched_channels`
 
             return searched.channel;
         }

core/pva/src/main/java/org/epics/pva/common/SearchRequest.java

@@ -85,7 +85,16 @@ public String toString()
     public static SearchRequest decode(final InetSocketAddress from, final byte version,
                                        final int payload, final ByteBuffer buffer)
     {
-        if (payload < 4+1+3+16+2+1+4+2)
+        // pvinfo sends 0x1D=29 bytes:
+        // Header and flags
+        // 0000 - CA 02 00 03 1D 00 00 00 00 00 00 00 81 00 00 00 - ................
+        // Return address
+        // 0010 - 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 - ................
+        // Return port uint16 0xB7C8, byte 0 protocols, uint16 0 channels
+        // 0020 - C8 B7 00 00 00
+        // Searches add 4 bytes for protocol (length 3) "tcp",
+        // plus the list of names.
+        if (payload < 4+1+3+16+2+1+2)
         {
             logger.log(Level.WARNING, "PVA client " + from + " sent only " + payload + " bytes for search request");
             return null;