flags: support flags that are just combinations of other flags, not taking a new bit. #660

Activity

1. lukewagner commented on Jun 15, 2026

   

   lukewagner

   on Jun 15, 2026

   Member

   More actions

   Thanks for filing; this seems like an interesting addition worth exploring!

   So currently, flags is defined as a specialization of records (as a record-of-bool-valued fields). If we added just the | extension (the ability to define a flag as the combination of other preceding flags), I think that framing still makes sense. If we also add the ability to define flag values as integer constants, then we probably need to switch to thinking of flags more like integers. That's not necessarily a problem, and is quite natural for C and other low-level languages, but probably requires some extra discussion since it might change whether the bindings generators for non-low-level-languages spit out a number vs. a record with boolean fields. Actually, I don't know what, e.g., componentize-{js,py} already do for flags; maybe they already use numbers? Anyone know?

   If we allow integer constants, there's also some questions of what the rules are for constants. E.g., can I have:

   flags f {
     a = 0x1,
     b = 0x2,
     c = 0x3
   }

   since c = a | b (and then would this be invalid if b was removed so that c was no longer the conjunction of multiple fields?) or do we only allow integer constants that are powers of 2 and non-powers-of-2 have to be expressed as conjunctions? I expect there are good answers, but it'll require some discussion of how much we want to lean into "they're just integers".

   To wit, looking at the current lifting rules (in lift_flat_flags in CanonicalABI.md), there is not a trap on stray bits (i.e., invalid flags values), but stray bits also don't propagate across component boundaries (so on the receiving end, you can assume a valid flags value) which implies a masking operation. Masking would continue to work with only-powers-of-2-integer-constants, but wouldn't in the general case for arbitrary constants, so that's another consideration.

   That's just some initial thoughts; happy to discuss more.
2. programmerjake commented on Jun 15, 2026

   

   programmerjake

   on Jun 15, 2026

   Last edited by programmerjake

   Author

   More actions

   ah, i was proposing that only literally 0 would be accepted, not arbitrary integer constants. so in terms of a record of bools, it would just be the record value where all fields are false.

   that said, I'm not against supporting integer constants if it makes sense.
3. dicej commented on Jun 15, 2026

   

   dicej

   on Jun 15, 2026

   Last edited by dicej

   Collaborator

   More actions

   For reference, componentize-py uses enum.Flag when generating code for WIT flags, which appears to be compatible with integer constants. ComponentizeJS generates an object with a bunch of boolean fields: https://github.com/bytecodealliance/jco/blob/2fd05be4b34137e720fe91043d2ce1232f66ac4d/crates/js-component-bindgen/src/ts_bindgen.rs#L1222-L1234
4. lukewagner commented on Jun 15, 2026

   

   lukewagner

   on Jun 15, 2026

   Member

   More actions

   @programmerjake Ahh, I see; just to indicate "no flags set". That nicely avoids a number of the trickier questions I listed.

   @dicej Thanks!

   So if we added |, I guess there's still a question of what JS bindings would do for combo values. Since there's also plenty of cases of Web APIs using JS numbers as bitfields (NodeFilter, compareDocumentPosition and, in WebGPU, GPUBufferUsage, GPUTextureUsage, etc), I wonder if the JS bindings should do that, and then each flags value can just be a Number-valued property. Probably also good for bindings performance. (cc @vados-cosmonic)
5. lukewagner commented on Jun 15, 2026

   

   lukewagner

   on Jun 15, 2026

   Member

   More actions

   Oh, hah, I just got to #662 in my inbox queue, which does seem to want integer constants other than 0.
6. programmerjake commented on Jun 15, 2026

   

   programmerjake

   on Jun 15, 2026

   Author

   More actions

   for integer values, we could continue to do masking and the mask would just be the bitwise or of all possible flags, so:

   flags f {
       a = 0b1,
       b = 0b1100,
       c = 0b1001,
   }
   

   would mask by 0b1101.
7. MendyBerger

   marked Allow specifying explicit values for flags #662 as a duplicate of this issue on Jun 16, 2026