FAQ - Adblock Plus internals

The hard work here is actually done by Gecko, the engine on top of which Firefox, Thunderbird and other applications are built. It allows something called "content policies". A content policy is simply a JavaScript (or C++) object that gets called whenever the browser needs to load something. It can then look at the address that should be loaded and some other data and decide whether it should be allowed. There is a number of built-in content policies (when you define which sites shouldn't be allowed to load images in Firefox or SeaMonkey, you are actually configuring one of these built-in content policies) and any extension can register one. So all that Adblock Plus has to do is to register its content policy, other than that there is only application logic to decide which addresses to block and user interface code to allow configuration of filters.

For developers: to register a content policy you have to write an XPCOM component that should implement the nsIContentPolicy interface. Make sure to adjust the module's registerSelf method to register your component in the "content-policy" category (use the category manager for this). That's it, now your component's shouldLoad method will be called and you can decide whether the specific request should be accepted or not.

All filters a translated into regular expressions internally, even the ones that haven't been specified as such. For example, the filter ad*banner.gif| will be translated into the regular expression /ad.*banner\.gif$/. However, when Adblock Plus is given an address that should be checked against all filters it doesn't simply test all filters one after another — that would slow down the browsing unnecessarily.

Besides of translating filters into regular expressions Adblock Plus also tries to extract text information from them. What it needs is a unique string of eight characters (a "shortcut") that must be present in every address matched by the filter (the length is arbitrary, eight just seems reasonable here). For example, if you have a filter |https://ad.* then Adblock Plus has the choice between "https://a", "ttp:https://ad" and "tp:https://ad.", any of these strings will always be present in whatever this filter will match. Unfortunately finding a shortcut for filters that simply don't have eight characters unbroken by wildcards or for filters that have been specified as regular expressions is impossible.

All shortcuts are put into a lookup table, Adblock Plus can find the filter by its shortcut very efficiently. Then, when a specific address has to be tested Adblock Plus will first look for known shortcuts there (this can be done very fast, the time needed is almost independent from the number of shortcuts). Only when a shortcut is found the string will be tested against the regular expression of the corresponding filter. However, filters without a shortcut still have to be tested one after another which is slow.

To sum up: which filters should be used to make a filter list fast? You should use as few regular expressions as possible, those are always slow. You also should make sure that simple filters have at least eight characters of unbroken text (meaning that these don't contain any characters with a special meaning like *), otherwise they will be just as slow as regular expressions. But with filters that qualify it doesn't matter how many filters you have, the processing time is always the same. That means that if you need 20 simple filters to replace one regular expression then it is still worth it. Speaking of which — the deregifier is very recommendable.

The filter matching algorithm in detail

Element hiding rules are translated into CSS and applied to all web pages the user is visiting. A rule like example.com#div(evil_ad) then looks like:

@-moz-document domain(example.com)
{
  div#evil_ad, div.evil_ad
  {
    display: none !important;
  }
}

@-moz-document is a proposed extension to the CSS standard, you can read more about it in the Mozilla Developer Center.

Rules that are not restricted to a certain domain will be restricted to the protocols https:// and https:// to prevent them from hiding elements of the browser's user interface (it is using the chrome:https:// protocol scheme). For example the rule #div(evil_ad) will be translated into:

@-moz-document url-prefix(https://),url-prefix(https://)
{
  div#evil_ad, div.evil_ad
  {
    display: none !important;
  }
}

For developers: Adblock Plus is using the stylesheet service here. This interface came with Gecko 1.8 and allows extensions to add user stylesheets dynamically (before that you could only modify userContent.css which requires you to restart the browser). User stylesheets will overwrite CSS code of all web sites, they have the highest possible importance.

Usually the first line of a filters file is simply [Adblock]. However, you might have noticed that recent versions of Adblock Plus sometimes put a different text instead. This is done when you have filters in your list that use advanced filter syntax only supported by newer versions of Adblock Plus but not original Adblock. One example would be:

(Adblock Plus 0.6.1.2 or higher required) [Adblock]

This is simply a comment. Adblock (and Adblock Plus for that reason) will ignore anything before the actual mark. The required Adblock Plus version is not enforced because Adblock Plus 0.6.1.2 didn't support it. However, if you use even newer filter syntax, you might get something like:

[Adblock Plus 0.7.1]

This type of header is supported starting with Adblock Plus 0.7.1. Older Adblock Plus versions and Adblock cannot open files starting with this header. As to the current versions, they will check the version number in the header and compare it with their own version number. If the file happens to require a newer Adblock Plus, the user will be given a message on import asking him to upgrade. Subscriptions will still load files meant for newer Adblock Plus versions but display a warning in the preferences dialog.

Finally, if you want to require Adblock Plus but don't want to specify the version number you can start the file with [Adblock Plus]. Of course this file will only be accepted by Adblock Plus 0.7.1 or higher again.