Performance guidelines for decl. WebRequest API

chrome/common/extensions/docs/templates/intros/events.html

 <p>
 An <code>Event</code> is an object
 that allows you to be notified
 when something interesting happens.
 Here's an example of using the
 <code>chrome.tabs.onCreated</code> event
 to be notified whenever there's a new tab:
 </p>
 
 <pre>
@@ skipping 146 matching lines @@
 
 <pre>
 var rule_ids = ["id1", "id2", ...];
 function getRules(rule_ids, function callback(details) {...});
 </pre>
 
 <p>
 The <code>details</code> parameter passed to the <code>callback()</code> function
 refers to an array of rules including filled optional parameters.
 </p>
+
+<h3 id="performance">Performance</h3>
+
+<p>
+To achieve maximum performance, you should keep the following guidelines in
+mind:
+<ul>
+  <li><p>Register and unregister rules in bulk. After each
+  registration or unregistration, Chrome needs to update internal data
+  structures. This update is an expensive operation.</p>
+  <p>Instead of</p>
+  <pre>
+var rule1 = {...};
+var rule2 = {...};
+chrome.declarativeWebRequest.onRequest.addRules([rule1]);
+chrome.declarativeWebRequest.onRequest.addRules([rule2]);</pre>
+  <p>prefer to write</p>
+  <pre>
+var rule1 = {...};
+var rule2 = {...};
+chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);</pre>
+  <li>Prefer substring matching over matching using regular expressions in a
+  $ref:events.UrlFilter.  Substring based matching is extremely fast.
+  <p>Instead of</p>
+  <pre>
+var match = new chrome.declarativeWebRequest.RequestMatcher({
+    url: {urlMatches: "example.com/[^?]*foo" } });</pre>
+  <p>prefer to write</p>
+  <pre>
+var match = new chrome.declarativeWebRequest.RequestMatcher({
+    url: {hostSuffix: "example.com", pathContains: "foo"} });</pre>
+  <li>If you have many rules that all share the same actions, you may merge
+  the rules into one because rules trigger their actions as soon as a single
+  condition is fulfilled. This speeds up the matching and reduces memory
+  consumption for duplicate action sets.
+  <p>Instead of</p>
+  <pre>
+var condition1 = new chrome.declarativeWebRequest.RequestMatcher({
+    url: { hostSuffix: 'example.com' } });
+var condition2 = new chrome.declarativeWebRequest.RequestMatcher({
+    url: { hostSuffix: 'foobar.com' } });
+var rule1 = { conditions: [condition1],
+              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
+var rule2 = { conditions: [condition2],
+              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
+chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);</pre>
+  <p>prefer to write</p>
+  <pre>
+var rule = { conditions: [condition1, condition2],
+             actions: [new chrome.declarativeWebRequest.CancelRequest()]};
+chrome.declarativeWebRequest.onRequest.addRules([rule]);</pre>
+</ul>
+</p>
 </div>
 {{/is_apps}}
 
 {{^is_apps}}
 <div class="doc-family extensions">
 <h2 id="filtered">Filtered events</h2>
 
 <p>Filtered events are a mechanism that allows listeners to specify a subset of
 events that they are interested in. A listener that makes use of a filter won't
 be invoked for events that don't pass the filter, which makes the listening
@@ skipping 26 matching lines @@
 of filters that an event supports will be listed in the documentation for that
 event in the "filters" section.</p>
 
 <p>When matching URLs (as in the example above), event filters support the same
 URL matching capabilities as expressible with a
   $ref:events.UrlFilter, except for scheme and port
 matching.</p>
 
 </div>
 {{/is_apps}}