README
¶
map-of-shame
⚠️ EXPERIMENTAL - DO NOT USE IN REAL SYSTEMS ⚠️
map-of-shame provides direct access to Go's internal map implementation through unsafe pointers.
Some code needs to perform operations on maps whose type is not known at compile time. Normally, this is done using reflection, which enforces various safety guarantees and prevents consumers from violating expectations of the runtime. However, this requires causes a large performance overhead - mainly by forcing most operations to allocate memory. The only alternative to this is to break the encapsulation of the runtime and expose internal functions and reimplement private types.
This library provides a thin wrapper around these exposed operations, so that consumers can merely focus on writing unsafe code.
You should not use this library. It serves a niche purpose that you do not have. If you do have it, you should write the subset of it that you need yourself. If you think you'll do a worse job than me, I can't stop you.
Why is this shameful?
If you read code for the Go runtime, especially code related to maps, you will find comments referencing libraries as members of the "hall of shame". These libraries exposed internal functions of the runtime for this purpose, so that they could write efficient code. The Go maintainers, not wanting these libraries to break, have had to quietly mark these methods as an unofficial backdoor API and maintain them in perpetuity. The whole situation is messy, and I find it easy to sympathize with people on both sides.
However, if many people repeatedly write the same code to break into the runtime and expose functionality because it's the best way to write efficient code, it seems obvious to me that there should be an officially-supported way to do this. This library exists mainly as a rough-draft proposal for an API extension for the unsafe package.
Documentation
¶
Index ¶
- type Iterator
- type Map
- func (m *Map) All(yield func(k, v unsafe.Pointer) bool)
- func (m *Map) Clear()
- func (m *Map) Delete(key unsafe.Pointer)
- func (m *Map) Get(key unsafe.Pointer) unsafe.Pointer
- func (m *Map) Iter() Iterator
- func (m *Map) Keys(yield func(k unsafe.Pointer) bool)
- func (m *Map) Len() int
- func (m *Map) Set(key, value unsafe.Pointer)
- func (m *Map) Values(yield func(v unsafe.Pointer) bool)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Iterator ¶
type Iterator struct {
// contains filtered or unexported fields
}
Iterator provides iteration over map key-value pairs.
func (*Iterator) InitAny ¶
InitAny initializes the iterator for any map value. It panics if m is not a map.
func (*Iterator) InitReflectTypePtr ¶
InitReflectTypePtr initializes the iterator for a map given its type and pointer. It panics if mapType is not a map type.
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map provides map operations for an unsafe.Pointer to a map.
func NewFromAny ¶
NewFromAny creates a Map from any map value. It panics if m is not a map.
func NewFromTypeAndPointer ¶
NewFromTypeAndPointer creates a Map from a map type and unsafe.Pointer to the map. It panics if mapType is not a map type.
func NewFromValue ¶
NewFromValue creates a Map from a reflect.Value. It panics if m is not a map.
func (*Map) Get ¶
Get returns a pointer to the value associated with key, or nil if the key is not present. The returned pointer points directly into the map and is only valid until the map is modified. Retaining this pointer may prevent the whole map from being garbage-collected.
Source Files