Fossil SCM
Expanded the "Why Not Bitfields?" discussion in www/caps/impl.md. Also tweaked the "Capability Letter Choices" text a bit while in there.
Commit
3ac560a2d0b9c811ff42f9ba7c2e98537d84ea59f8a64e27e820b3b73a7c9c89
Parent
c6cdf9ce8e95df1…
1 file changed
+29
-12
+29
-12
| --- www/caps/impl.md | ||
| +++ www/caps/impl.md | ||
| @@ -1,16 +1,17 @@ | ||
| 1 | 1 | # Implementation Details of User Capabilities |
| 2 | 2 | |
| 3 | 3 | ## <a name="choices"></a>Capability Letter Choices |
| 4 | 4 | |
| 5 | -We assigned user capability characters using only lowercase ASCII | |
| 5 | +We [assigned][ref] user capability characters using only lowercase ASCII | |
| 6 | 6 | letters at first, so those are the most important within Fossil: they |
| 7 | 7 | control the functions most core to Fossil’s operation. Once we used up |
| 8 | 8 | most of the lowercase letters, we started using uppercase, and then |
| 9 | 9 | during the development of the [forum feature][for] we assigned most of |
| 10 | -the decimal numerals. Eventually, we might have to start using | |
| 11 | -punctuation. We expect to run out of reasons to define new caps before | |
| 10 | +the decimal numerals. All of the lowercase ASCII letters are now | |
| 11 | +assigned. Eventually, we might have to start using ASCII | |
| 12 | +punctuation and symbols. We expect to run out of reasons to define new caps before | |
| 12 | 13 | we’re forced to switch to Unicode, though the possibilities for [mnemonic][mn] |
| 13 | 14 | assignments with emoji are intriguing. <span style="vertical-align: |
| 14 | 15 | bottom">😉</span> |
| 15 | 16 | |
| 16 | 17 | The existing caps are usually mnemonic, especially among the |
| @@ -20,21 +21,37 @@ | ||
| 20 | 21 | unused. |
| 21 | 22 | |
| 22 | 23 | |
| 23 | 24 | ## <a name="bitfield"></a>Why Not Bitfields? |
| 24 | 25 | |
| 25 | -When Fossil is deciding whether a user has a given capability, it simply | |
| 26 | -searches the cap string for a given character. This is slower than | |
| 27 | -checking bits in a bitfield, but it’s fast enough in the context where | |
| 28 | -it runs: at the front end of an HTTP request handler, where the | |
| 29 | -nanosecond differences in such implementation details are completely | |
| 30 | -swamped by the millisecond scale ping time of that repo’s network | |
| 31 | -connection, followed by the requires I/O to satisfy the request. A | |
| 32 | -[`strchr()` call](https://en.cppreference.com/w/c/string/byte/strchr) is | |
| 33 | -plenty fast in that context. | |
| 26 | +Some may question the use of ASCII character strings for [capability | |
| 27 | +sets][ucap] instead of bitfields, which are more efficient, both in | |
| 28 | +terms of storage and processing time. | |
| 29 | + | |
| 30 | +Fossil handles these character strings in one of two ways. For most HTTP | |
| 31 | +hits, Fossil [expands][sexp] the string into a [`struct` full of | |
| 32 | +flags][sff] so that later code can just do simple Boolean tests. In a | |
| 33 | +minority of cases, where Fossil only needs to check for the presence of | |
| 34 | +a single flag, it just does a [`strchr()` call][sc] on the string | |
| 35 | +instead. | |
| 36 | + | |
| 37 | +Both methods are slower than bit testing in a bitfield, but keep the | |
| 38 | +execution context in mind: at the front end of an HTTP request handler, | |
| 39 | +where the nanosecond differences in such implementation details are | |
| 40 | +completely swamped by the millisecond scale ping time of that repo’s | |
| 41 | +network connection, followed by the required I/O to satisfy the request. | |
| 42 | +Either method is plenty fast in that context. | |
| 43 | + | |
| 44 | +In exchange for this immeasurable cost per hit, we get human-readable | |
| 45 | +capability sets. | |
| 34 | 46 | |
| 35 | 47 | ----- |
| 36 | 48 | |
| 37 | 49 | *[Back to Administering User Capabilities](./)* |
| 38 | 50 | |
| 39 | 51 | [for]: ./forum.wiki |
| 40 | 52 | [mn]: https://en.wikipedia.org/wiki/Mnemonic |
| 53 | +[ref]: ./ref.html | |
| 54 | +[sexp]: http://fossil-scm.org/fossil/artifact?udc=1&ln=1223-1298&name=889d6724 | |
| 55 | +[sff]: http://fossil-scm.org/fossil/artifact?udc=1&ln=80-117&name=52d2860f | |
| 56 | +[sc]: https://en.cppreference.com/w/c/string/byte/strchr | |
| 57 | +[ucap]: ./index.md#ucap | |
| 41 | 58 |
| --- www/caps/impl.md | |
| +++ www/caps/impl.md | |
| @@ -1,16 +1,17 @@ | |
| 1 | # Implementation Details of User Capabilities |
| 2 | |
| 3 | ## <a name="choices"></a>Capability Letter Choices |
| 4 | |
| 5 | We assigned user capability characters using only lowercase ASCII |
| 6 | letters at first, so those are the most important within Fossil: they |
| 7 | control the functions most core to Fossil’s operation. Once we used up |
| 8 | most of the lowercase letters, we started using uppercase, and then |
| 9 | during the development of the [forum feature][for] we assigned most of |
| 10 | the decimal numerals. Eventually, we might have to start using |
| 11 | punctuation. We expect to run out of reasons to define new caps before |
| 12 | we’re forced to switch to Unicode, though the possibilities for [mnemonic][mn] |
| 13 | assignments with emoji are intriguing. <span style="vertical-align: |
| 14 | bottom">😉</span> |
| 15 | |
| 16 | The existing caps are usually mnemonic, especially among the |
| @@ -20,21 +21,37 @@ | |
| 20 | unused. |
| 21 | |
| 22 | |
| 23 | ## <a name="bitfield"></a>Why Not Bitfields? |
| 24 | |
| 25 | When Fossil is deciding whether a user has a given capability, it simply |
| 26 | searches the cap string for a given character. This is slower than |
| 27 | checking bits in a bitfield, but it’s fast enough in the context where |
| 28 | it runs: at the front end of an HTTP request handler, where the |
| 29 | nanosecond differences in such implementation details are completely |
| 30 | swamped by the millisecond scale ping time of that repo’s network |
| 31 | connection, followed by the requires I/O to satisfy the request. A |
| 32 | [`strchr()` call](https://en.cppreference.com/w/c/string/byte/strchr) is |
| 33 | plenty fast in that context. |
| 34 | |
| 35 | ----- |
| 36 | |
| 37 | *[Back to Administering User Capabilities](./)* |
| 38 | |
| 39 | [for]: ./forum.wiki |
| 40 | [mn]: https://en.wikipedia.org/wiki/Mnemonic |
| 41 |
| --- www/caps/impl.md | |
| +++ www/caps/impl.md | |
| @@ -1,16 +1,17 @@ | |
| 1 | # Implementation Details of User Capabilities |
| 2 | |
| 3 | ## <a name="choices"></a>Capability Letter Choices |
| 4 | |
| 5 | We [assigned][ref] user capability characters using only lowercase ASCII |
| 6 | letters at first, so those are the most important within Fossil: they |
| 7 | control the functions most core to Fossil’s operation. Once we used up |
| 8 | most of the lowercase letters, we started using uppercase, and then |
| 9 | during the development of the [forum feature][for] we assigned most of |
| 10 | the decimal numerals. All of the lowercase ASCII letters are now |
| 11 | assigned. Eventually, we might have to start using ASCII |
| 12 | punctuation and symbols. We expect to run out of reasons to define new caps before |
| 13 | we’re forced to switch to Unicode, though the possibilities for [mnemonic][mn] |
| 14 | assignments with emoji are intriguing. <span style="vertical-align: |
| 15 | bottom">😉</span> |
| 16 | |
| 17 | The existing caps are usually mnemonic, especially among the |
| @@ -20,21 +21,37 @@ | |
| 21 | unused. |
| 22 | |
| 23 | |
| 24 | ## <a name="bitfield"></a>Why Not Bitfields? |
| 25 | |
| 26 | Some may question the use of ASCII character strings for [capability |
| 27 | sets][ucap] instead of bitfields, which are more efficient, both in |
| 28 | terms of storage and processing time. |
| 29 | |
| 30 | Fossil handles these character strings in one of two ways. For most HTTP |
| 31 | hits, Fossil [expands][sexp] the string into a [`struct` full of |
| 32 | flags][sff] so that later code can just do simple Boolean tests. In a |
| 33 | minority of cases, where Fossil only needs to check for the presence of |
| 34 | a single flag, it just does a [`strchr()` call][sc] on the string |
| 35 | instead. |
| 36 | |
| 37 | Both methods are slower than bit testing in a bitfield, but keep the |
| 38 | execution context in mind: at the front end of an HTTP request handler, |
| 39 | where the nanosecond differences in such implementation details are |
| 40 | completely swamped by the millisecond scale ping time of that repo’s |
| 41 | network connection, followed by the required I/O to satisfy the request. |
| 42 | Either method is plenty fast in that context. |
| 43 | |
| 44 | In exchange for this immeasurable cost per hit, we get human-readable |
| 45 | capability sets. |
| 46 | |
| 47 | ----- |
| 48 | |
| 49 | *[Back to Administering User Capabilities](./)* |
| 50 | |
| 51 | [for]: ./forum.wiki |
| 52 | [mn]: https://en.wikipedia.org/wiki/Mnemonic |
| 53 | [ref]: ./ref.html |
| 54 | [sexp]: http://fossil-scm.org/fossil/artifact?udc=1&ln=1223-1298&name=889d6724 |
| 55 | [sff]: http://fossil-scm.org/fossil/artifact?udc=1&ln=80-117&name=52d2860f |
| 56 | [sc]: https://en.cppreference.com/w/c/string/byte/strchr |
| 57 | [ucap]: ./index.md#ucap |
| 58 |