components/network_hints/renderer/dns_prefetch_queue.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // DnsQueue is implemented as an almost FIFO circular buffer for text
   6 // strings that don't have embedded nulls ('\0').  The "almost" element is that
   7 // some duplicate strings may be removed (i.e., the string won't really be
   8 // pushed *if* the class happens to notice that a duplicate is already in the
   9 // queue).
  10 // The buffers internal format is null terminated character strings
  11 // (a.k.a., c_strings).
  12 // It is written to be as fast as possible during push() operations, so
  13 // that there will be minimal performance impact on a supplier thread.
  14 // The push() operation will not block, and no memory allocation is involved
  15 // (internally) during the push operations.
  16 // The one caveat is that if there is insufficient space in the buffer to
  17 // accept additional string via a push(), then the push() will fail, and
  18 // the buffer will be unmodified.
  19
  20 // This class was designed for use in DNS prefetch operations.  During
  21 // rendering, the supplier is the renderer (typically), and the consumer
  22 // is a thread that sends messages to an async DNS resolver.
  23
  24 #ifndef COMPONENTS_NETWORK_HINTS_RENDERER_DNS_PREFETCH_QUEUE_H__
  25 #define COMPONENTS_NETWORK_HINTS_RENDERER_DNS_PREFETCH_QUEUE_H__
  26
  27 #include <string>
  28
  29 #include "base/basictypes.h"
  30 #include "base/memory/scoped_ptr.h"
  31
  32 namespace network_hints {
  33
  34 // A queue of DNS lookup requests for internal use within the network_hints
  35 // component.
  36 class DnsQueue {
  37  public:
  38   // BufferSize is a signed type used for indexing into a buffer.
  39   typedef int32 BufferSize;
  40
  41   enum PushResult { SUCCESSFUL_PUSH, OVERFLOW_PUSH, REDUNDANT_PUSH };
  42
  43   // The size specified in the constructor creates a buffer large enough
  44   // to hold at most one string of that length, or "many"
  45   // strings of considerably shorter length.  Note that strings
  46   // are padded internally with a terminal '\0" while stored,
  47   // so if you are trying to be precise and get N strings of
  48   // length K to fit, you should actually construct a buffer with
  49   // an internal size of N*(K+1).
  50   explicit DnsQueue(BufferSize size);
  51   ~DnsQueue(void);
  52
  53   size_t Size() const { return size_; }
  54   void Clear();
  55
  56   // Push takes an unterminated string of the given length
  57   // and inserts it into the queue for later
  58   // extraction by read.  For each successful push(), there
  59   // can later be a corresponding read() to extracted the text.
  60   // The string must not contain an embedded null terminator
  61   // Exactly length chars are written, or the push fails (where
  62   // "fails" means nothing is written).
  63   // Returns true for success, false for failure (nothing written).
  64   PushResult Push(const char* source, const size_t length);
  65
  66   PushResult Push(std::string source) {
  67     return Push(source.c_str(), source.length());
  68   }
  69
  70   // Extract the next available string from the buffer.
  71   // If the buffer is empty, then return false.
  72   bool Pop(std::string* out_string);
  73
  74  private:
  75   bool Validate();  // Checks that all internal data is valid.
  76
  77   const scoped_ptr<char[]> buffer_;  // Circular buffer, plus extra char ('\0').
  78   const BufferSize buffer_size_;  // Size one smaller than allocated space.
  79   const BufferSize buffer_sentinel_;  // Index of extra '\0' at end of buffer_.
  80
  81   // If writable_ == readable_, then the buffer is empty.
  82   BufferSize readable_;  // Next readable char in buffer_.
  83   BufferSize writeable_;  // The next space in buffer_ to push.
  84
  85   // Number of queued strings
  86   size_t size_;
  87
  88   DISALLOW_COPY_AND_ASSIGN(DnsQueue);
  89 };  // class DnsQueue
  90
  91 }  // namespace network_hints
  92
  93 #endif  // COMPONENTS_NETWORK_HINTS_RENDERER_DNS_PREFETCH_QUEUE_H__