base/README.md

   1 # What is this
   2 Contains a written down set of principles and other information on //base.
   3 Please add to it!
   4
   5 ## About //base:
   6
   7 Chromium is a very mature project. Most things that are generally useful are
   8 already here and things not here aren't generally useful.
   9
  10 Base is pulled into many projects. For example, various ChromeOS daemons. So
  11 the bar for adding stuff is that it must have demonstrated wide
  12 applicability. Prefer to add things closer to where they're used (i.e. "not
  13 base"), and pull into base only when needed.  In a project our size,
  14 sometimes even duplication is OK and inevitable.
  15
  16 Adding a new logging macro `DPVELOG_NE` is not more clear than just
  17 writing the stuff you want to log in a regular logging statement, even
  18 if it makes your calling code longer. Just add it to your own code.
  19
  20 If the code in question does not need to be used inside base, but will have
  21 multiple consumers across the codebase, consider placing it in a new directory
  22 under components/ instead.
  23
  24 ## Qualifications for being in //base OWNERS
  25   * interest and ability to learn low level/high detail/complex c++ stuff
  26   * inclination to always ask why and understand everything (including external
  27     interactions like win32) rather than just hoping the author did it right
  28   * mentorship/experience
  29   * demonstrated good judgement (esp with regards to public APIs) over a length
  30     of time
  31
  32 Owners are added when a contributor has shown the above qualifications and
  33 when they express interest. There isn't an upper bound on the number of OWNERS.
  34
  35 ## Design and naming
  36   * Be sure to use the base namespace.
  37   * STL-like constructs should adhere as closely to STL as possible. Functions
  38     and behaviors not present in STL should only be added when they are related
  39     to the specific data structure implemented by the container.
  40   * For STL-like constructs our policy is that they should use STL-like naming
  41     even when it may conflict with the style guide. So functions and class names
  42     should be lower case with underscores. Non-STL-like classes and functions
  43     should use Google naming.
  44
  45 ## Performance testing
  46
  47 Since the primitives provided by //base are used very widely, it is important to
  48 ensure they scale to the necessary workloads and perform well under all
  49 supported platforms. The `base_perftests` target is a suite of
  50 synthetic microbenchmarks that measure performance in various scenarios:
  51
  52   * BasicPostTaskPerfTest: Exercises MessageLoopTaskRunner's multi-threaded
  53     queue in isolation.
  54   * ConditionVariablePerfTest: Measures thread switching cost of condition
  55     variables.
  56   * IntegratedPostTaskPerfTest: Exercises the full MessageLoop/RunLoop
  57     machinery.
  58   * JSONPerfTest: Tests JSONWriter and JSONReader performance.
  59   * MessageLoopPerfTest: Measures the speed of task posting in various
  60     configurations.
  61   * ObserverListPerfTest: Exercises adding, removing and signalling observers.
  62   * PthreadEventPerfTest: Establishes the baseline thread switching cost using
  63     pthreads.
  64   * ScheduleWorkTest: Measures the overhead of MessagePump::ScheduleWork.
  65   * SequenceManagerPerfTest: Benchmarks SequenceManager scheduling with various
  66     underlying task runners.
  67   * TaskObserverPerfTest: Measures the incremental cost of adding task
  68     observers.
  69   * TaskPerfTest: Checks the cost of posting tasks between threads.
  70   * WaitableEvent{Thread,}PerfTest: Measures waitable events in single and
  71     multithreaded scenarios.
  72
  73 Regressions in these benchmarks can generally by caused by 1) operating system
  74 changes, 2) compiler version or flag changes or 3) changes in //base code
  75 itself.