docs: private static void tryAutoAttachingWithConnection(SlotReference slot, Client client) throws IOException, InterruptedException, TimeoutException {
          // Keeps track of the files we might be able to auto-attach, grouped and sorted by the playlist they
          // were created from, where playlist 0 means all tracks.
          final Map<Integer, LinkedList<MetadataCache>> candidateGroups = gatherCandidateAttachmentGroups();
          MetadataCache match = null;  // We will close any non-matched files from the candidateGroups in our finally clause,
          // but we will leave this one open because we are returning it.
          try {
              // Set up a menu request to process each group.
              for (Map.Entry<Integer,LinkedList<MetadataCache>> entry : candidateGroups.entrySet()) {
                  final LinkedList<MetadataCache> candidates;
                  ArrayList<Integer> tracksToSample;
                  if (client.tryLockingForMenuOperations(MetadataFinder.MENU_TIMEOUT, TimeUnit.SECONDS)) {
                      try {
                          final int playlistId = entry.getKey();
                          candidates = entry.getValue();
                          final long count = getTrackCount(slot.slot, client, playlistId);
                          if (count == Message.NO_MENU_RESULTS_AVAILABLE || count == 0) {
                              // No tracks available to match this set of candidates.
                              for (final MetadataCache candidate : candidates) {
                                  candidate.close();
                              }
                              candidates.clear();
                          }
  
                          // Filter out any candidates with the wrong number of tracks.
                          final Iterator<MetadataCache> candidateIterator = candidates.iterator();
                          while (candidateIterator.hasNext()) {
                              final MetadataCache candidate = candidateIterator.next();
                              if (candidate.trackCount != count) {
                                  candidate.close();
                                  candidateIterator.remove();
                              }
                          }
  
                          // Bail before querying any metadata if we can already rule out all the candidates.
                          if (candidates.isEmpty()) {
                              continue;
                          }
  
                          // Gather as many track IDs as we are configured to sample, up to the number available
                          tracksToSample = chooseTrackSample(slot, client, (int) count);
                      } finally {
                          client.unlockForMenuOperations();
                      }
                  } else {
                      throw new TimeoutException("Unable to lock player for menu operations.");
                  }
  
                  // Winnow out any auto-attachment candidates that don't match any sampled track
                  for (final int trackId : tracksToSample) {
                      logger.info("Comparing track " + trackId + " with " + candidates.size() + " metadata cache file(s).");
  
                      final DataReference reference = new DataReference(slot, trackId);
                      final TrackMetadata track = MetadataFinder.getInstance().queryMetadata(reference, CdjStatus.TrackType.REKORDBOX, client);
                      if (track == null) {
                          logger.warn("Unable to retrieve metadata when attempting cache auto-attach for slot {}, giving up", slot);
                          return;
                      }
  
                      for (int i = candidates.size() - 1; i >= 0; --i) {
                          final MetadataCache candidate = candidates.get(i);
                          if (!track.equals(candidate.getTrackMetadata(null, reference))) {
                              candidate.close();
                              candidates.remove(i);
                          }
                      }
  
                      if (candidates.isEmpty()) {
                          break;  // No point sampling more tracks, we have ruled out all candidates in this group.
                      }
                  }
  
                  if (candidates.isEmpty()) {
                      continue;  // This group has failed; move on to the next candidate group, if any.
                  }
  
                  match = candidates.get(0);  // We have found at least one matching cache, use the first.
                  logger.info("Auto-attaching metadata cache " + match.getName() + " to slot " + slot);
                  MetadataFinder.getInstance().attachMetadataCacheInternal(slot, match);
                  return;
              }
          } finally {  // No matter how we leave this function, close any of the remaining zip files we are not attaching.
              for (Map.Entry<Integer, LinkedList<MetadataCache>> entry : candidateGroups.entrySet()) {
                  for (MetadataCache candidate : entry.getValue()) {
                      if (candidate != match) {
                          candidate.close();
                      }
                  }
              }
          }
      }