HTTP::XSHeaders(3)

NAME
HTTP::XSHeaders - Fast XS Header library, replacing HTTP::Headers and HTTP::Headers::Fast.

VERSION
Version 1.000001

SYNOPSIS
    # load once
    use HTTP::XSHeaders;

    # keep using HTTP::Headers or HTTP::Headers::Fast as you wish

ALPHA RELEASE
This is a work in progress. Once we feel it is stable, the version will be bumped to 1.0. Until then, feel free to use and try and submit tickets, but do this at your own risk.

DESCRIPTION
By loading HTTP::XSHeaders anywhere, you replace any usage of HTTP::Headers and HTTP::Headers::Fast with a fast C implementation.

You can continue to use HTTP::Headers and HTTP::Headers::Fast and any other module that depends on them just like you did before. It's just faster now.

Since version 0.400000 HTTP::XSHeaders is considered Thread-Safe.

WHY
First there was HTTP::Headers. It's good, stable, and ubiquitous. However, it's slow.

Along came HTTP::Headers::Fast. Gooder, stable, and used internally by Plack, so you know it means business.

Not fast enough, we implemented an XS version of it, released under the name HTTP::Headers::Fast::XS. It was a successful experiment. However, we thought we could do better.

HTTP::XSHeaders provides a complete rework of the headers library with the intent of being fast, lean, and clear. It does not attempt to implement the original algorithm, but instead uses its own C-level implementation with an interface that is mostly compatible with both HTTP::Headers and HTTP::Headers::Fast.

This module attempts to replace "HTTP::Headers", "HTTP::Headers::Fast", and the XS implementation of it, "HTTP::Headers::Fast::XS". We attempt to continue developing this module and perhaps deprecate "HTTP::Headers::Fast::XS".

COMPATIBILITY
While we keep compatibility with the interfaces of HTTP::Headers and HTTP::Headers::Fast, we've taken the liberty to make several changes that were deemed reasonable and sane:

•   Aligning in "as_string" method

    "as_string" method does weird stuff in order to keep the original indentation. This is unnecessary and unhelpful. We simply add one space as indentation after the first newline.

•   Normalisation of header names

    When a given header is one of the standard HTTP headers, we convert it to the standard casing; otherwise, we normalise it by:

    •   Converting each underscore to a hyphen.

    •   Converting the first letter of each word to uppercase.

    •   Converting the rest of the letters of each word to lowercase.

    For example:

    •   Accept-Encoding => Accept-Encoding

    •   www-authenticate => WWW-Authenticate (notice the weird standard case for WWW)

    •   my_header => My-Header

•   Literal header names using leading colon are not supported

    Following the previous item, we don't treat an initial colon character in any special way.

•   $TRANSLATE_UNDERSCORE is not supported

    $TRANSLATE_UNDERSCORE (which controls whether underscores are translated or not) is not supported. It's barely documented (or isn't at all), it isn't used by anything on CPAN, nor can we find any use-case other than the tests. So, instead, we always convert underscores to dashes.

•   Storable is loaded but not used

    Both HTTP::Headers and HTTP::Headers::Fast use Storable for cloning. While "HTTP::Headers" loads it automatically, "HTTP::Headers::Fast" loads it lazily.

    Since we override both, we load "Storable" always. However, we do not use it for cloning and instead implemented our C-level struct cloning.

BENCHMARKS
    HTTP::Headers 6.05, HTTP::Headers::Fast 0.19, HTTP::XSHeaders 0.200000

    -- as_string
    Implementation  Time
    xsheaders       0.00468778222396934
    fast            0.0964434631535363
    orig            0.105793242864311

    -- as_string_without_sort
    Implementation            Time
    xsheaders_as_str          0.00475378949036912
    xsheaders_as_str_wo       0.00484256407093758
    fast_as_str               0.0954295831126767
    fast_as_str_wo            0.0736790240349744
    orig                      0.105823918835043

    -- get_content_length
    Implementation  Time
    xsheaders       0.0105355231679
    fast            0.0121647090348415
    orig            0.0574727505777773

    -- get_date
    Implementation  Time
    xsheaders       0.077750453123065
    fast            0.0826203668485442
    orig            0.101090469267193

    -- get_header
    Implementation  Time
    xsheaders       0.00505807073565111
    fast            0.0612525710276364
    orig            0.0820842156588862

    -- push_header
    Implementation  Time
    xsheaders       0.00271070907120684
    fast            0.0178986201816726
    orig            0.0242003530752845

    -- push_header_many
    Implementation  Time
    xsheaders       0.00426636619488888
    fast            0.0376390665501822
    orig            0.0503843871625857

    -- scan
    Implementation  Time
    xsheaders       0.0142865143596716
    fast            0.061759048917916
    orig            0.0667217048891246

    -- set_date
    Implementation  Time
    xsheaders       0.114970609213125
    fast            0.130542749562301
    orig            0.168121156055091

    -- set_header
    Implementation  Time
    xsheaders       0.0456117003715809
    fast            0.0868535344701981
    orig            0.135920422020881

METHODS/ATTRIBUTES
These match the API described in HTTP::Headers and HTTP::Headers::Fast, with the caveats described under COMPATIBILITY.

Please see those modules for documentation on what these methods and attributes are.

  new

  as_string

  as_string_without_sort

  authorization

  authorization_basic

  clear

  clone

  content_encoding

  content_is_html

  content_is_xhtml

  content_is_xml

  content_language

  content_length

  content_type

  content_type_charset

  date

  expires

  from

  header

  header_field_names

  if_modified_since

  if_unmodified_since

  init_header

  last_modified

  proxy_authenticate

  proxy_authorization

  proxy_authorization_basic

  push_header

  referer

  referrer

  remove_content_headers

  remove_header

  scan

  server

  title

  user_agent

  warnings

  www_authenticate

AUTHORS

•   Gonzalo Diethelm "gonzalo.diethelm AT gmail DOT com"

•   Sawyer X "xsawyerx AT gmail DOT com"

THANKS

•   Rafaël Garcia-Suarez

•   p5pclub

•   Christian Hansen