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:

[Mike West, 2013/04/08 13:52:53]

These are excellent tips: I think they'd be even more excellent if you add
example code demonstrating the right way to do things. Developers generally end
up copy/pasting; it'd be good to give them something to start with.

[battre, 2013/04/08 14:42:55]

Done.

+<ul>
+  <li>Register and unregister rules in bulk. After each
+  registration or unregistration, Chrome needs to update internal data
+  structures. This update is an expensive operation.
+  <li>Prefer substring matching over matching using regular expressions in a
+  $ref:events.UrlFilter.  Substring based matching is extremely fast.
+  <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.
+</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}}