Fossil

Check-in [3ac560a2]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Expanded the "Why Not Bitfields?" discussion in www/caps/impl.md. Also tweaked the "Capability Letter Choices" text a bit while in there.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | caps-doc
Files: files | file ages | folders
SHA3-256: 3ac560a2d0b9c811ff42f9ba7c2e98537d84ea59f8a64e27e820b3b73a7c9c89
User & Date: wyoung 2019-08-28 22:09:02.339
Context
2019-08-28
22:42
Assorted small improvements to top-level caps doc ... (check-in: f21bfbee user: wyoung tags: caps-doc)
22:09
Expanded the "Why Not Bitfields?" discussion in www/caps/impl.md. Also tweaked the "Capability Letter Choices" text a bit while in there. ... (check-in: 3ac560a2 user: wyoung tags: caps-doc)
2019-08-27
20:35
Moved www/capabilities.md to www/caps/index.md and www/admin-v-setup.md to www/caps/admin-v-setup.md. Then broke three chunks of the old capabilities.md doc out into new www/caps/* docs: login groups, implementation details of user capabilities, and the user capability reference material. The latter switched from Markdown to HTML format so we could make it a clearer-looking table, rather than its prior hard-to-read bullet list form. ... (check-in: c6cdf9ce user: wyoung tags: caps-doc)
Changes
Unified Diff Ignore Whitespace Patch
Changes to www/caps/impl.md. 
1
2
3
4
5
6
7
8
9

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24



25






26
27
28
29
30
31
32
33



34
35
36
37
38
39
40






# Implementation Details of User Capabilities

## <a name="choices"></a>Capability Letter Choices

We assigned user capability characters using only lowercase ASCII
letters at first, so those are the most important within Fossil: they
control the functions most core to Fossil’s operation. Once we used up
most of the lowercase letters, we started using uppercase, and then
during the development of the [forum feature][for] we assigned most of

the decimal numerals.  Eventually, we might have to start using
punctuation. We expect to run out of reasons to define new caps before
we’re forced to switch to Unicode, though the possibilities for [mnemonic][mn]
assignments with emoji are intriguing. <span style="vertical-align:
bottom">😉</span>

The existing caps are usually mnemonic, especially among the
earliest and therefore most central assignments, made when we still had
lots of letters to choose from.  There is still hope for good future
mnemonic assignments among the uppercase letters, which are mostly still
unused.


## <a name="bitfield"></a>Why Not Bitfields?




When Fossil is deciding whether a user has a given capability, it simply






searches the cap string for a given character. This is slower than
checking bits in a bitfield, but it’s fast enough in the context where
it runs: at the front end of an HTTP request handler, where the
nanosecond differences in such implementation details are completely
swamped by the millisecond scale ping time of that repo’s network
connection, followed by the requires I/O to satisfy the request. A
[`strchr()` call](https://en.cppreference.com/w/c/string/byte/strchr) is
plenty fast in that context.




-----

*[Back to Administering User Capabilities](./)*

[for]:  ./forum.wiki
[mn]:   https://en.wikipedia.org/wiki/Mnemonic










|




>
|
|













>
>
>
|
>
>
>
>
>
>
|
|
|
|
|
|
<
|
>
>
>







>
>
>
>
>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

# Implementation Details of User Capabilities

## <a name="choices"></a>Capability Letter Choices

We [assigned][ref] user capability characters using only lowercase ASCII
letters at first, so those are the most important within Fossil: they
control the functions most core to Fossil’s operation. Once we used up
most of the lowercase letters, we started using uppercase, and then
during the development of the [forum feature][for] we assigned most of
the decimal numerals. All of the lowercase ASCII letters are now
assigned. Eventually, we might have to start using ASCII
punctuation and symbols. We expect to run out of reasons to define new caps before
we’re forced to switch to Unicode, though the possibilities for [mnemonic][mn]
assignments with emoji are intriguing. <span style="vertical-align:
bottom">😉</span>

The existing caps are usually mnemonic, especially among the
earliest and therefore most central assignments, made when we still had
lots of letters to choose from.  There is still hope for good future
mnemonic assignments among the uppercase letters, which are mostly still
unused.


## <a name="bitfield"></a>Why Not Bitfields?

Some may question the use of ASCII character strings for [capability
sets][ucap] instead of bitfields, which are more efficient, both in
terms of storage and processing time.

Fossil handles these character strings in one of two ways. For most HTTP
hits, Fossil [expands][sexp] the string into a [`struct` full of
flags][sff] so that later code can just do simple Boolean tests. In a
minority of cases, where Fossil only needs to check for the presence of
a single flag, it just does a [`strchr()` call][sc] on the string
instead.

Both methods are slower than bit testing in a bitfield, but keep the
execution context in mind: at the front end of an HTTP request handler,
where the nanosecond differences in such implementation details are
completely swamped by the millisecond scale ping time of that repo’s
network connection, followed by the required I/O to satisfy the request.

Either method is plenty fast in that context.

In exchange for this immeasurable cost per hit, we get human-readable
capability sets.

-----

*[Back to Administering User Capabilities](./)*

[for]:  ./forum.wiki
[mn]:   https://en.wikipedia.org/wiki/Mnemonic
[ref]:  ./ref.html
[sexp]: http://fossil-scm.org/fossil/artifact?udc=1&ln=1223-1298&name=889d6724
[sff]:  http://fossil-scm.org/fossil/artifact?udc=1&ln=80-117&name=52d2860f
[sc]:   https://en.cppreference.com/w/c/string/byte/strchr
[ucap]: ./index.md#ucap