doc/Programming-Guide/01_Main.dox

   1 /*
   2  * Copyright (C) 1996-2020 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 /**
  10 \mainpage Squid 3.x Developer Programming Guide
  11
  12 \section Abstract Abstract
  13
  14 \par
  15      Squid is a WWW Cache application developed by the National Laboratory
  16      for Applied Network Research and members of the Web Caching community.
  17      Squid is implemented as a single, non-blocking process based around
  18      a BSD select() loop.  This document describes the operation of the Squid
  19      source code and is intended to be used by others who wish to customize
  20      or improve it.
  21
  22
  23 \section Introduction Introduction
  24
  25 \par
  26         The Squid source code has evolved more from empirical
  27         observation and tinkering, rather than a solid design
  28         process.  It carries a legacy of being "touched" by
  29         numerous individuals, each with somewhat different techniques
  30         and terminology.
  31
  32 \par
  33         Squid is a single-process proxy server.  Every request is
  34         handled by the main process, with the exception of FTP.
  35         However, Squid does not use a "threads package" such has
  36         Pthreads.  While this might be easier to code, it suffers
  37         from portability and performance problems.  Instead Squid
  38         maintains data structures and state information for each
  39         active request.
  40
  41 \par
  42         The code is often difficult to follow because there are no
  43         explicit state variables for the active requests.  Instead,
  44         thread execution progresses as a sequence of "callback
  45         functions" which get executed when I/O is ready to occur,
  46         or some other event has happened.  As a callback function
  47         completes, it is responsible for registering the next
  48         callback function for subsequent I/O.
  49
  50 \par
  51         Note there is only a pseudo-consistent naming scheme.  In
  52         most cases functions are named like \c moduleFooBar() .
  53         However, there are also some functions named like
  54         \c module_foo_bar() .
  55
  56 \par
  57         Note that the Squid source changes rapidly, and while we
  58         do make some effort to document code as we go some parts
  59         of the documentation may be left out.  If you find any
  60         inconsistencies, please feel free to notify
  61         http://www.squid-cache.org/Support/contact.dyn the Squid Developers.
  62
  63  */