@@ -499,10 +499,17 @@ public void clear() {
499499 }
500500
501501 /**
502- * Remove any entries that have been garbage collected and are no longer referenced.
503- * Under normal circumstances garbage collected entries are automatically purged as
504- * items are added or removed from the Map. This method can be used to force a purge,
505- * and is useful when the Map is read frequently but updated less often.
502+ * Remove any entries that have been garbage-collected and are no longer referenced.
503+ * Note that this call implies segment locking and can lead to thread contention.
504+ * <p>Under normal circumstances, garbage-collected entries are automatically purged as
505+ * items are added or removed from the Map. This method can be used to force a purge
506+ * which is useful when the Map is read frequently but hardly ever updated anymore.
507+ * <p>Note that it may be preferable to simply {@link #clear() clear} the entire cache at
508+ * certain points of the lifecycle, not just dropping unreferenced entries but even the
509+ * entire cache content: assuming that most entries in the cache won't be needed anymore
510+ * after certain processing phases, therefore rather rebuilding the cache going forward.
511+ * @since 4.1.1
512+ * @see #clear()
506513 */
507514 public void purgeUnreferencedEntries () {
508515 for (Segment segment : this .segments ) {
@@ -716,7 +723,7 @@ void restructureIfNecessary(boolean allowResize) {
716723 int currCount = this .count .get ();
717724 boolean needsResize = allowResize && (currCount > 0 && currCount >= this .resizeThreshold );
718725 Reference <K , V > ref = this .referenceManager .pollForPurge ();
719- if (ref != null || ( needsResize ) ) {
726+ if (ref != null || needsResize ) {
720727 restructure (allowResize , ref );
721728 }
722729 }
0 commit comments