FieldFlags.jl Documentation
FieldFlags.jl is a small package without dependencies, giving users the ability to create structs containing packed integers of various bitsizes.
The two main exports of this package are the two macros @bitflags
and @bitfield
, for creating bit packed boolean flag structs and bit packed integer field structs respectively.
This package is heavily inspired by C-style bitfields, though there are some limitations.
Goals
- Low/Negligible overhead
- I can get a
bextract
on my machine from extremely high level julia code
- I can get a
- High performance
- Good optimization by the compiler (constant folding, elimination of error paths)
- The package should "feel" as if there were no special implementation
- Good debuggability with JET.jl
Limitations
- Thread safety
- Accessing the objects produced by this package is not thread safe and atomic access is not planned to be supported. Users are advised to use proper locking to ensure safety.
- Size of the objects
- Due to a compiler limitation, the size of all objects created by this package is a multiple of 8 bits. This restriction may be removed in the future.
- Type parameters cannot be supported - the size of a field needs to be known at definition time, so that the various bitshifts and masking operations done internally can be compiled away.
- The widest a field can currently be is
8*sizeof(UInt)
bits, asUInt
is currently the default return type for fields (other than those of width1
, which return aBool
).
Planned Features
- Custom field type annotations
- This would look like a regular field type annotation for exact sizes (i.e.
a::UInt16
), or like e.g.a:3::UInt16
for objects that want to store the lower 3 bits of anUInt16
and want to get that type back out when accessing the field. - Due to the nature of how these objects are stored internally, the types will need to be at least
isbitstype
, possibly evenisprimitivetype
, as it's unclear whether the padding potentially contained in anisbitstype
is legal to observe (I suspect it isn't). <: Signed
types will need to be at least 2 bits in size, to store the sign bit.- See #9 for the issue tracking this.
- This would look like a regular field type annotation for exact sizes (i.e.