Update the ERRORS section in the docs.

README.rst

@@ -983,21 +983,9 @@ state. They are removed permanently when the VCL instance is discarded
 ERRORS
 ======
 
-The method documentation above refers to two kinds of failures: method
-failure and VCL failure.
-
-When a method fails, an error message is written to the Varnish log
-with the ``VCL_Error`` tag. If the method's return type allows for a
-distinguished "error" value, such as NULL for ``.string()``, then that
-value is returned. VCL processing can then continue (although your
-code should of course check for the error).
-
-For some return types, there is no such distinguished value; for
-example for INT as returned by ``.integer()``. In such cases, VCL
-failues is invoked.
-
-VCL failure has the same results as if ``return(fail)`` is called from
-a VCL subroutine:
+The method documentation above describes illegal uses for which VCL
+failure is invoked. VCL failure has the same results as if
+``return(fail)`` is called from a VCL subroutine:
 
 * If the failure occurs in ``vcl_init``, then the VCL load fails with
   an error message.
@@ -1010,6 +998,28 @@ a VCL subroutine:
 * If the failure occurs in ``vcl_synth``, then ``vcl_synth`` is
   aborted, and the response line "503 VCL failed" is sent.
 
+VCL failure is meant to "fail fast" on conditions that cannot be
+correct, or when resource limitations such as workspace exhaustion
+prevent further processing. Depending on your use case, you may be
+able to use the VMOD's methods without risk of failure. For example,
+if it is known that none of the strings in a set have common prefixes,
+then methods with ``select=UNIQUE`` can be used safely after calling
+``.hasprefix()``.
+
+If you need to check against possible failure conditions:
+
+* If ``.nmatches() == 1``, then ``select=UNIQUE`` can be used safely.
+
+* The ``UNIQUE`` and ``EXACT`` conditions can also be checked with
+  ``.matched(select=UNIQUE)`` and ``.matched(select=EXACT)``.
+
+* The ``allow_overlaps`` flag can be set in the constructor, to
+  ensure that VCL load fails if a set unintentionally has strings
+  with common prefixes.
+
+See `LIMITATIONS`_ for considerations if you encounter conditions such
+as workspace exhaustion.
+
 LOGGING
 =======
 

src/vmod_selector.vcc

@@ -871,21 +871,9 @@ state. They are removed permanently when the VCL instance is discarded
 ERRORS
 ======
 
-The method documentation above refers to two kinds of failures: method
-failure and VCL failure.
-
-When a method fails, an error message is written to the Varnish log
-with the ``VCL_Error`` tag. If the method's return type allows for a
-distinguished "error" value, such as NULL for ``.string()``, then that
-value is returned. VCL processing can then continue (although your
-code should of course check for the error).
-
-For some return types, there is no such distinguished value; for
-example for INT as returned by ``.integer()``. In such cases, VCL
-failues is invoked.
-
-VCL failure has the same results as if ``return(fail)`` is called from
-a VCL subroutine:
+The method documentation above describes illegal uses for which VCL
+failure is invoked. VCL failure has the same results as if
+``return(fail)`` is called from a VCL subroutine:
 
 * If the failure occurs in ``vcl_init``, then the VCL load fails with
   an error message.
@@ -898,6 +886,28 @@ a VCL subroutine:
 * If the failure occurs in ``vcl_synth``, then ``vcl_synth`` is
   aborted, and the response line "503 VCL failed" is sent.
 
+VCL failure is meant to "fail fast" on conditions that cannot be
+correct, or when resource limitations such as workspace exhaustion
+prevent further processing. Depending on your use case, you may be
+able to use the VMOD's methods without risk of failure. For example,
+if it is known that none of the strings in a set have common prefixes,
+then methods with ``select=UNIQUE`` can be used safely after calling
+``.hasprefix()``.
+
+If you need to check against possible failure conditions:
+
+* If ``.nmatches() == 1``, then ``select=UNIQUE`` can be used safely.
+
+* The ``UNIQUE`` and ``EXACT`` conditions can also be checked with
+  ``.matched(select=UNIQUE)`` and ``.matched(select=EXACT)``.
+
+* The ``allow_overlaps`` flag can be set in the constructor, to
+  ensure that VCL load fails if a set unintentionally has strings
+  with common prefixes.
+
+See `LIMITATIONS`_ for considerations if you encounter conditions such
+as workspace exhaustion.
+
 LOGGING
 =======