1# What is this 2Contains a written down set of principles and other information on //base. 3Please add to it! 4 5## About //base: 6 7Chromium is a very mature project. Most things that are generally useful are 8already here and things not here aren't generally useful. 9 10The bar for adding stuff to base is that it must have demonstrated wide 11applicability. Prefer to add things closer to where they're used (i.e. "not 12base"), and pull into base only when needed. In a project our size, 13sometimes even duplication is OK and inevitable. 14 15Adding a new logging macro `DPVELOG_NE` is not more clear than just 16writing the stuff you want to log in a regular logging statement, even 17if it makes your calling code longer. Just add it to your own code. 18 19If the code in question does not need to be used inside base, but will have 20multiple consumers across the codebase, consider placing it in a new directory 21under components/ instead. 22 23base is written for the Chromium project and is not intended to be used 24outside it. Using base outside of src.git is explicitly not supported, 25and base makes no guarantees about API (or even ABI) stability (like all 26other code in Chromium). New code that depends on base/ must be in 27src.git. Code that's not in src.git but pulled in through DEPS (for 28example, v8) cannot use base. 29 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 36 of time 37 38Owners are added when a contributor has shown the above qualifications and 39when they express interest. There isn't an upper bound on the number of OWNERS. 40 41## Design and naming 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. 50 51## Performance testing 52 53Since the primitives provided by //base are used very widely, it is important to 54ensure they scale to the necessary workloads and perform well under all 55supported platforms. The `base_perftests` target is a suite of 56synthetic microbenchmarks that measure performance in various scenarios: 57 58 * BasicPostTaskPerfTest: Exercises MessageLoopTaskRunner's multi-threaded 59 queue in isolation. 60 * ConditionVariablePerfTest: Measures thread switching cost of condition 61 variables. 62 * IntegratedPostTaskPerfTest: Exercises the full MessageLoop/RunLoop 63 machinery. 64 * JSONPerfTest: Tests JSONWriter and JSONReader performance. 65 * MessageLoopPerfTest: Measures the speed of task posting in various 66 configurations. 67 * ObserverListPerfTest: Exercises adding, removing and signalling observers. 68 * PartitionLockPerfTest: Tests the implementation of Lock used in 69 PartitionAlloc 70 * PthreadEventPerfTest: Establishes the baseline thread switching cost using 71 pthreads. 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 77 observers. 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. 84 85Regressions in these benchmarks can generally by caused by 1) operating system 86changes, 2) compiler version or flag changes or 3) changes in //base code 87itself. 88