Document that .compile() is deprecated.

README.rst

@@ -29,7 +29,6 @@ SYNOPSIS
                            [, BOOL allow_overlaps])
   VOID <obj>.add(STRING [, STRING string] [, STRING regex]
 		 [, BACKEND backend] [, INT integer])
-  VOID <obj>.compile()
   VOID <obj>.create_stats()
 
   # Matching
@@ -105,7 +104,6 @@ lines. For example::
       url_prefix.add("/foo/", backend=foo_backend);
       url_prefix.add("/bar/", backend=bar_backend);
       url_prefix.add("/baz/", backend=baz_backend);
-      url_prefix.compile();
 
       # For requests with these Host headers, generate a redirect
       # response, using the associated string to construct the
@@ -115,7 +113,6 @@ lines. For example::
       redirect.add("www.bar.com", string="/bar", integer=302);
       redirect.add("www.baz.com", string="/baz", integer=303);
       redirect.add("www.quux.com", string="/quux", integer=307);
-      redirect.compile();
 
       # Requests for these URLs are rewritten by altering the
       # query string, using the associated regex for a
@@ -125,7 +122,6 @@ lines. For example::
       rewrite.add("/alpha/beta", regex="(\?.*)\bfoo=[^&]+&?(.*)$");
       rewrite.add("/delta/gamma", regex="(\?.*)\bbar=[^&]+&?(.*)$");
       rewrite.add("/epsilon/zeta", regex="(\?.*)\bbaz=[^&]+&?(.*)$");
-      rewrite.compile();
   }
 
   sub vcl_recv {
@@ -400,6 +396,28 @@ always succeed after ``.has_prefix()`` matches (and to fail fast if
 the restriction is not met). By default, ``allow_overlaps`` is
 ``true``.
 
+The initialization of a set is completed when ``vcl_init`` finishes,
+or when the deprecated ``.compile()`` method is called. This prepares
+the set for use with the strings added with the ``.add()`` method
+described below. The VCL load fails if:
+
+* The same string is added to the same set more than once (that string
+  is included in the error message).
+
+* The set contains a string that is a prefix of another string in the
+  same set, but ``allow_overlaps`` was set to ``false`` in the
+  constructor.
+
+Set initialization may also fail due to conditions such as out of
+memory.
+
+If no strings were added to the set before ``vcl_init`` finishes or
+``.compile()`` is invoked, the VCL load will not fail, but all match
+operations on the set will fail. In that case, a warning is emitted to
+the log with the ``VCL_Error`` tag. Since that happens outside of any
+request/response transaction, the error message can only be seen when
+a tool like ``varnishlog(1)`` is used with raw grouping (``-g raw``).
+
 Examples::
 
   sub vcl_init {
@@ -449,12 +467,12 @@ Regular expressions are evaluated exactly as native regexen in VCL.
 ``.add()`` invokes VCL failure if it is called in any subroutine
 besides ``vcl_init``. The VCL load fails if:
 
-* The set has already been compiled.
-
 * The string to be added is NULL.
 
 * A regular expression in the ``regex`` parameter fails to compile.
 
+* The deprecated ``.compile()`` method has already been called.
+
 Example::
 
   sub vcl_init {
@@ -464,7 +482,6 @@ Example::
       myset.add("www.baz.com", string="/baz", backend=baz_backend);
       myset.add("www.quux.com", string="/quux", backend=quux_backend,
       		regex="^/quux/([^/]+)/");
-      myset.compile();
   }
 
 .. _xset.compile():
@@ -472,33 +489,17 @@ Example::
 VOID xset.compile()
 -------------------
 
-Compile the set. This must be done for every set, after all of the
-strings have been added.
+**This method is deprecated**, and will be removed in a future
+version.  ``.compile()`` may be omitted, since compilation happens
+automatically when ``vcl_init`` finishes.
 
-``.compile()`` invokes VCL failure if it is called in any subroutine
-besides ``vcl_init``. The VCL load fails if:
-
-* The same string is added to the same set more than once (that string
-  is included in the error message).
-
-* The set contains a string that is a prefix of another string in the
-  same set, but ``allow_overlaps`` was set to ``false`` in the
-  constructor.
-
-* The set has already been compiled.
+``.compile()`` compiles the set. This is done after all of the strings
+have been added.
 
-* The compilation fails for any other reason (probably out of memory).
-
-To re-state the rules about the order of ``.add()`` and ``.compile()``
-more simply: in ``vcl_init``, add all of the strings to the set, then
-compile the set.
-
-If no strings were added to the set before ``.compile()`` is invoked,
-the VCL load will not fail, but all match operations on the set will
-fail. In that case, a warning is emitted to the log with the
-``VCL_Error`` tag. Since that happens outside of any request/response
-transaction, the error message can only be seen when a tool like
-``varnishlog(1)`` is used with raw grouping (``-g raw``).
+``.compile()`` invokes VCL failure if it is called in any subroutine
+besides ``vcl_init``. The VCL load may fail for the same reasons
+described for set initialization above, or if ``.compile()`` is
+invoked more than once.
 
 .. _xset.create_stats():
 
@@ -507,12 +508,11 @@ VOID xset.create_stats()
 
 Create statistics counters for this object that are displayed by tools
 such as ``varnishstat(1)``. See `STATISTICS`_ for details.  It must be
-called in ``vcl_init`` after the set is compiled. No statistics are
-created for a set object if ``.create_stats()`` is not invoked.
+called in ``vcl_init``. No statistics are created for a set object if
+``.create_stats()`` is not invoked.
 
 ``.create_stats()`` invokes VCL failure if it is called in any VCL
-subroutine besides ``vcl_init``. The VCL load fails if it is called
-before the set is compiled.
+subroutine besides ``vcl_init``.
 
 Example::
 
@@ -521,7 +521,6 @@ Example::
       myset.add("foo");
       myset.add("bar");
       myset.add("baz");
-      myset.compile();
       myset.create_stats();
   }
 

src/vmod_selector.vcc

@@ -25,7 +25,6 @@ SYNOPSIS
                            [, BOOL allow_overlaps])
   VOID <obj>.add(STRING [, STRING string] [, STRING regex]
 		 [, BACKEND backend] [, INT integer])
-  VOID <obj>.compile()
   VOID <obj>.create_stats()
 
   # Matching
@@ -101,7 +100,6 @@ lines. For example::
       url_prefix.add("/foo/", backend=foo_backend);
       url_prefix.add("/bar/", backend=bar_backend);
       url_prefix.add("/baz/", backend=baz_backend);
-      url_prefix.compile();
 
       # For requests with these Host headers, generate a redirect
       # response, using the associated string to construct the
@@ -111,7 +109,6 @@ lines. For example::
       redirect.add("www.bar.com", string="/bar", integer=302);
       redirect.add("www.baz.com", string="/baz", integer=303);
       redirect.add("www.quux.com", string="/quux", integer=307);
-      redirect.compile();
 
       # Requests for these URLs are rewritten by altering the
       # query string, using the associated regex for a
@@ -121,7 +118,6 @@ lines. For example::
       rewrite.add("/alpha/beta", regex="(\?.*)\bfoo=[^&]+&?(.*)$");
       rewrite.add("/delta/gamma", regex="(\?.*)\bbar=[^&]+&?(.*)$");
       rewrite.add("/epsilon/zeta", regex="(\?.*)\bbaz=[^&]+&?(.*)$");
-      rewrite.compile();
   }
 
   sub vcl_recv {
@@ -386,6 +382,28 @@ always succeed after ``.has_prefix()`` matches (and to fail fast if
 the restriction is not met). By default, ``allow_overlaps`` is
 ``true``.
 
+The initialization of a set is completed when ``vcl_init`` finishes,
+or when the deprecated ``.compile()`` method is called. This prepares
+the set for use with the strings added with the ``.add()`` method
+described below. The VCL load fails if:
+
+* The same string is added to the same set more than once (that string
+  is included in the error message).
+
+* The set contains a string that is a prefix of another string in the
+  same set, but ``allow_overlaps`` was set to ``false`` in the
+  constructor.
+
+Set initialization may also fail due to conditions such as out of
+memory.
+
+If no strings were added to the set before ``vcl_init`` finishes or
+``.compile()`` is invoked, the VCL load will not fail, but all match
+operations on the set will fail. In that case, a warning is emitted to
+the log with the ``VCL_Error`` tag. Since that happens outside of any
+request/response transaction, the error message can only be seen when
+a tool like ``varnishlog(1)`` is used with raw grouping (``-g raw``).
+
 Examples::
 
   sub vcl_init {
@@ -423,12 +441,12 @@ Regular expressions are evaluated exactly as native regexen in VCL.
 ``.add()`` invokes VCL failure if it is called in any subroutine
 besides ``vcl_init``. The VCL load fails if:
 
-* The set has already been compiled.
-
 * The string to be added is NULL.
 
 * A regular expression in the ``regex`` parameter fails to compile.
 
+* The deprecated ``.compile()`` method has already been called.
+
 Example::
 
   sub vcl_init {
@@ -438,49 +456,31 @@ Example::
       myset.add("www.baz.com", string="/baz", backend=baz_backend);
       myset.add("www.quux.com", string="/quux", backend=quux_backend,
       		regex="^/quux/([^/]+)/");
-      myset.compile();
   }
 
 $Method VOID .compile()
 
-Compile the set. This must be done for every set, after all of the
-strings have been added.
+**This method is deprecated**, and will be removed in a future
+version.  ``.compile()`` may be omitted, since compilation happens
+automatically when ``vcl_init`` finishes.
 
-``.compile()`` invokes VCL failure if it is called in any subroutine
-besides ``vcl_init``. The VCL load fails if:
-
-* The same string is added to the same set more than once (that string
-  is included in the error message).
-
-* The set contains a string that is a prefix of another string in the
-  same set, but ``allow_overlaps`` was set to ``false`` in the
-  constructor.
-
-* The set has already been compiled.
+``.compile()`` compiles the set. This is done after all of the strings
+have been added.
 
-* The compilation fails for any other reason (probably out of memory).
-
-To re-state the rules about the order of ``.add()`` and ``.compile()``
-more simply: in ``vcl_init``, add all of the strings to the set, then
-compile the set.
-
-If no strings were added to the set before ``.compile()`` is invoked,
-the VCL load will not fail, but all match operations on the set will
-fail. In that case, a warning is emitted to the log with the
-``VCL_Error`` tag. Since that happens outside of any request/response
-transaction, the error message can only be seen when a tool like
-``varnishlog(1)`` is used with raw grouping (``-g raw``).
+``.compile()`` invokes VCL failure if it is called in any subroutine
+besides ``vcl_init``. The VCL load may fail for the same reasons
+described for set initialization above, or if ``.compile()`` is
+invoked more than once.
 
 $Method VOID .create_stats(PRIV_TASK)
 
 Create statistics counters for this object that are displayed by tools
 such as ``varnishstat(1)``. See `STATISTICS`_ for details.  It must be
-called in ``vcl_init`` after the set is compiled. No statistics are
-created for a set object if ``.create_stats()`` is not invoked.
+called in ``vcl_init``. No statistics are created for a set object if
+``.create_stats()`` is not invoked.
 
 ``.create_stats()`` invokes VCL failure if it is called in any VCL
-subroutine besides ``vcl_init``. The VCL load fails if it is called
-before the set is compiled.
+subroutine besides ``vcl_init``.
 
 Example::
 
@@ -489,7 +489,6 @@ Example::
       myset.add("foo");
       myset.add("bar");
       myset.add("baz");
-      myset.compile();
       myset.create_stats();
   }