2 Contains a written down set of principles and other information on //base.
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.
10 The bar for adding stuff to base is that it must have demonstrated wide
11 applicability. Prefer to add things closer to where they're used (i.e. "not
12 base"), and pull into base only when needed. In a project our size,
13 sometimes even duplication is OK and inevitable.
15 Adding a new logging macro `DPVELOG_NE` is not more clear than just
16 writing the stuff you want to log in a regular logging statement, even
17 if it makes your calling code longer. Just add it to your own code.
19 If the code in question does not need to be used inside base, but will have
20 multiple consumers across the codebase, consider placing it in a new directory
21 under components/ instead.
23 base is written for the Chromium project and is not intended to be used
24 outside it. Using base outside of src.git is explicitly not supported,
25 and base makes no guarantees about API (or even ABI) stability (like all
26 other code in Chromium). New code that depends on base/ must be in
27 src.git. Code that's not in src.git but pulled in through DEPS (for
28 example, v8) cannot use base.
30 ## Qualifications for being in //base OWNERS
31 * interest and ability to learn low level/high detail/complex c++ stuff
32 * inclination to always ask why and understand everything (including external
33 interactions like win32) rather than just hoping the author did it right
34 * mentorship/experience
35 * demonstrated good judgement (esp with regards to public APIs) over a length
38 Owners are added when a contributor has shown the above qualifications and
39 when they express interest. There isn't an upper bound on the number of OWNERS.
42 * Be sure to use the base namespace.
43 * STL-like constructs should adhere as closely to STL as possible. Functions
44 and behaviors not present in STL should only be added when they are related
45 to the specific data structure implemented by the container.
46 * For STL-like constructs our policy is that they should use STL-like naming
47 even when it may conflict with the style guide. So functions and class names
48 should be lower case with underscores. Non-STL-like classes and functions
49 should use Google naming.
51 ## Performance testing
53 Since the primitives provided by //base are used very widely, it is important to
54 ensure they scale to the necessary workloads and perform well under all
55 supported platforms. The `base_perftests` target is a suite of
56 synthetic microbenchmarks that measure performance in various scenarios:
58 * BasicPostTaskPerfTest: Exercises MessageLoopTaskRunner's multi-threaded
60 * ConditionVariablePerfTest: Measures thread switching cost of condition
62 * IntegratedPostTaskPerfTest: Exercises the full MessageLoop/RunLoop
64 * JSONPerfTest: Tests JSONWriter and JSONReader performance.
65 * MessageLoopPerfTest: Measures the speed of task posting in various
67 * ObserverListPerfTest: Exercises adding, removing and signalling observers.
68 * PartitionLockPerfTest: Tests the implementation of Lock used in
70 * PthreadEventPerfTest: Establishes the baseline thread switching cost using
72 * RandUtilPerfTest: Measures the time it takes to generate random numbers.
73 * ScheduleWorkTest: Measures the overhead of MessagePump::ScheduleWork.
74 * SequenceManagerPerfTest: Benchmarks SequenceManager scheduling with various
75 underlying task runners.
76 * TaskObserverPerfTest: Measures the incremental cost of adding task
78 * TaskPerfTest: Checks the cost of posting tasks between threads.
79 * ThreadLocalStoragePerfTest: Exercises different mechanisms for accessing
80 data associated with the current thread (C++ `thread_local`, the
81 implementation in //base, the POSIX/WinAPI directly)
82 * WaitableEvent{Thread,}PerfTest: Measures waitable events in single and
83 multithreaded scenarios.
85 Regressions in these benchmarks can generally by caused by 1) operating system
86 changes, 2) compiler version or flag changes or 3) changes in //base code