Forem: arshia_rgh

🧩Golang Type Memory Representation Quick Reference

arshia_rgh — Fri, 17 Oct 2025 12:04:15 +0000

This article may be updated and improved later

This article provides a quick reference for Go types and their actual memory representation. Instead of focusing on syntax or usage, it explains what happens under the hood when you create a value of each type — how it is stored in memory, its internal structure, and its size on 32-bit and 64-bit architectures.

Pointer

What is: Memory address pointing to another value.

unsafe.Pointer
*int, *string ...

Memory:
- 64-bit -> 8 bytes
- 32-bit -> 4 bytes
Note: A pointer can be nil, meaning it points to nothing.

String

What is: Pointer to its underlying Bytes + len

type StringHeader struct {
    Data uintptr
    Len  int
}

Memory: A pointer + int
- 64-bit -> 8 + 8 = 16 bytes
- 32-bit -> 4 + 4 = 8 bytes

Int, Float, complex(real + imaginary floats) or uint

If a numeric type is not explicitly sized (for example int or uint), its size depends on the architecture — 32-bit or 64-bit.

If the type is explicitly sized (int8, int64, complex64, etc.), its memory size matches the type name.

For example:

int → 4 bytes on 32-bit, 8 bytes on 64-bit
complex64 → 8 bytes (two float32 values)

Slice

What is: Pointer to its underlying Bytes + len + cap

type SliceHeader struct {
    Data uintptr
    Len  int
    Cap  int
}

Memory:
- 64-bit -> 8 + 8 + 8 = 24 bytes
- 32-bit -> 4 + 4 + 4 = 12 bytes
Note: Nillable. A slice is nil when its data pointer is nil and both len and cap are zero.

Map

What is: Pointer to the struct hmap(no_swiss) (maps.Map for the swiss)
Memory:
- 64-bit -> 8 bytes
- 32-bit -> 4 bytes
Note: Nillable (It is a Pointer)

Chan

What is: Pointer to the struct hchan
Memory:
- 64-bit -> 8 bytes
- 32-bit -> 4 bytes
Note: Nillable (It is a Pointer)

Struct

What is: Inline layout of its fields. If it has no fields, it occupies zero bytes.
Memory: Sum of field sizes + alignment padding. which are 8 bytes or 4 bytes ( based on the architecture)

type Example struct {
    A int8   // 1 byte
    B int32  // 4 bytes
}

In the above example, the total size will be 8 bytes (on 64-bit) due to alignment padding.

type Example2 struct {
    A int64  // 8 bytes
    B bool   // 1 Bytes
}

Example2 will occupy 16 bytes on a 64-bit system.

Interface

What is: Two Pointers(Type info pointer + data pointer)

type EmptyInterface struct {
    Type *Type
    Data unsafe.Pointer
}

type NonEmptyInterface struct {
    ITab *ITab
    Data unsafe.Pointer
}

Memory:
- 64-bit -> 8 + 8 = 16 Bytes
- 32-bit -> 4 + 4 = 8 Bytes
Note: Nillable. An interface is nil when both its type and data pointers are nil.

Func

What is: Pointer to the function's code in memory.
Memory:
- 64-bit -> 8 Bytes
- 32-bit -> 4 Bytes
Note: Nillable, (It is a Pointer).

Category	Type	Size (64-bit)	Size (32-bit)	Note
Boolean	`bool`	1 byte	1 byte	Represents `true` or `false`. May include padding in structs.
Integer (Signed)	`int8`	1	1	8-bit signed integer.
	`int16`	2	2	16-bit signed integer.
	`int32`	4	4	32-bit signed integer.
	`int64`	8	8	64-bit signed integer.
	`int`	8	4	Machine word-sized integer (depends on architecture).
Integer (Unsigned)	`uint8`	1	1	8-bit unsigned integer (alias: `byte`).
	`uint16`	2	2	16-bit unsigned integer.
	`uint32`	4	4	32-bit unsigned integer.
	`uint64`	8	8	64-bit unsigned integer.
	`uint`	8	4	Machine word-sized unsigned integer.
	`uintptr`	8	4	Unsigned integer large enough to store a pointer.
Text Types	`string`	16	8	Struct: pointer to data + length (`Data uintptr`, `Len int`). Immutable.
	`rune`	4	4	Alias for `int32`, represents a Unicode code point.
	`byte`	1	1	Alias for `uint8`, represents a raw byte.
Floating Point	`float32`	4	4	32-bit IEEE 754 floating-point number.
	`float64`	8	8	64-bit IEEE 754 floating-point number.
Complex Numbers	`complex64`	8	8	Two `float32` values: real + imaginary (4 + 4).
	`complex128`	16	16	Two `float64` values: real + imaginary (8 + 8).
Composite Types	`array`	varies	varies	Fixed-length, contiguous block of elements. Value type.
	`slice`	24	12	Struct: pointer + length + capacity (`Data uintptr`, `Len int`, `Cap int`). Reference type.
	`struct`	varies	varies	Inline fields + alignment padding. Value type.
	`map`	8	4	Pointer to `runtime.hmap` (hash table). Reference type.
	`chan`	8	4	Pointer to `runtime.hchan` (channel buffer & state). Reference type.
	`interface`	16	8	Struct: type info pointer + data pointer (`itab*`, `data unsafe.Pointer`). Reference type.
	`pointer` (`*T`)	8	4	Direct memory address pointing to value of type `T`.
	`function`	8	4	Pointer to it's code.
Special Types	`nil`	—	—	Zero value for reference types. No memory allocation.
Unsafe / Runtime	`unsafe.Pointer`	8	4	Untyped pointer; can convert to/from `uintptr`.
Empty Struct	`struct{}`	0	0	Takes no space; used for signals or markers.

🛠️ Golang Source Code Essentials, Part 1: The unsafe Package — Breaking Go’s Safety for Power

arshia_rgh — Tue, 14 Oct 2025 14:15:50 +0000

Go is a statically typed language, which means type safety is checked and enforced at compile time. The compiler makes sure you can’t mix up types or misuse values, that’s one of the reasons Go programs are so stable and reliable.
But Go also has a small, dangerous, and extremely powerful back door called the unsafe package.
This package lets you step outside the type system and talk directly to memory, no safety checks, no compiler protection. It exists mainly for the Go runtime itself, but developers can use it too, at their own risk.

When you use unsafe, you’re saying, “I know what I’m doing,” and if you’re wrong, the crash (or silent corruption) is on you. In return, you get access to things like raw pointers, custom memory layouts, and performance tricks that would otherwise be impossible in pure Go.

Similar concepts exist in other statically typed languages such as Java (via sun.misc.Unsafe) and Rust (with its unsafe blocks). They all serve the same purpose — to give developers a way to break safety rules when they absolutely need to, usually for performance or low-level operations like system calls and pointer manipulation.

By the end of this article, you’ll understand:

Why the runtime needs the unsafe package
What the unsafe package really provides
How it allows you to reinterpret memory and manipulate addresses
How to use it safely and what uintptr actually is
Where unsafe lives in Go’s source code and how it’s implemented
And finally, how to do some fun (and slightly dangerous 😄) things using unsafe

⚙️ Why the Runtime Needs `Unsafe` Power

At first glance, Go looks like the kind of language that would never need something like unsafe.It’s memory-safe, garbage-collected, and statically typed, three things that usually keep you far away from raw memory operations.

So why does the Go runtime rely so heavily on it?

The answer is simple: because safety itself requires control.

The runtime, the layer that manages goroutines, memory allocation, garbage collection, and scheduling, sits closer to the hardware than any other part of Go. It can’t build itself using only the safe abstractions that ordinary Go code depends on, because those abstractions depend on the runtime(classic chicken-and-egg problem😅).To create and manage the safety guarantees that the rest of the language enjoys, the runtime sometimes has to step outside those guarantees. That’s where unsafe comes in.

Here are a few concrete examples:

Memory layout control – The runtime needs to know exactly how structs, slices, and objects are arranged in memory to implement the garbage collector and scheduler efficiently. Go’s regular reflection APIs aren’t low-level enough for that.
Direct pointer manipulation: When the runtime needs to link objects in memory (like connecting goroutine stacks or marking heap objects), it can’t afford the overhead or indirection of safe pointer conversions.
Interacting with CPU or OS boundaries: Certain operations, such as reading atomic counters or interacting with system-specific memory regions, require direct access to raw addresses.
Performance-critical code: In parts of the runtime that run constantly — like garbage collection or goroutine scheduling — every nanosecond matters. Eliminating even a small layer of abstraction can make a big difference.

In all these cases, unsafe acts as the bridge between Go’s managed world and the machine’s raw memory. It’s what allows the runtime to bend the rules temporarily so that those same rules can be enforced safely everywhere else.You can think of it like the runtime reaching beneath the language’s safety net to make sure the net itself doesn’t tear.

Of course, this power comes with serious responsibility.

When something goes wrong inside the runtime, a bad pointer conversion, a misaligned atomic operation, or an incorrect memory assumption, the entire Go process can crash instantly. That’s why unsafe and other internal packages are tightly restricted to the runtime and standard library. They exist to make Go possible, not for day-to-day application development.

But it’s important to note that the unsafe package isn’t hidden or private, it’s part of Go’s public standard library, and that’s intentional.
The Go team designed it this way so that developers could still use it in rare cases where direct memory access or type manipulation is absolutely necessary.
Many real-world projects already rely on unsafe for performance-critical or low-level work (as discussed in this research )

🧠 Core Functions and Types in the `unsafe` Package

The unsafe package is one of the smallest in the Go standard library, yet it’s also one of the most powerful and dangerous.
It doesn’t import anything, it doesn’t depend on the runtime, and it contains only a handful of functions and types. But those few tools give you direct access to the raw memory that Go normally protects you from.

🧩 The Core Types

There are only two key types in unsafe:

unsafe.Pointer: a special kind of pointer that can point to anything. It’s not tied to any specific type, and Go lets you convert between unsafe.Pointer and other pointer types freely.

Example:

  var f float64 = 3.14
  p := unsafe.Pointer(&f)
  i := (*uint64)(p)
  fmt.Println(*i)

Here, we’re reinterpreting the memory of a float64 as a uint64, just reading the same bits differently.

uintptr — an integer large enough to hold a pointer value(8 byte or 4 byte ...). It’s used when you need to perform arithmetic on addresses (for example, offsetting a pointer manually). But unlike unsafe.Pointer, a uintptr doesn’t keep the memory alive, the garbage collector treats it as a number, not a reference. So converting between them requires caution:

Look at this example:

var a int = 5
var aPtr = &a

var a int = 5
aPtr := uintptr(unsafe.Pointer(&a))

In the first case, the GC knows there’s a pointer to a, so it won’t collect it, But in the second case, aPtr is just an integer — a can be garbage collected.
As the Go documentation warns, you should not store a uintptr in a variable and use it later.
Instead, use it directly, like this:

p := unsafe.Pointer(uintptr(unsafe.Pointer(&arr[0])) + unsafe.Sizeof(arr[0])*i)

⚖️ The Utility Functions

unsafe also includes a few key functions that reveal how Go’s runtime lays things out in memory:

Sizeof(x) → returns the size in bytes of the value x.
Alignof(x) → tells you the alignment requirements of a variable.
Offsetof(x) → gives you the byte offset of a struct field.

Together, these functions let you understand and control how Go arranges your data in memory.

New APIs in the newer Go versions:

Add(ptr, len) → adds len to the ptr and returns the updated ptr
Slice(ptr, len) → returns a slice that underlying array starts at ptr and len and cap is the len argument
SliceData(slice) → returns the ptr to the underlying array of the slice argument
String(ptr, len) → returns a string that underlying bytes starts at ptr and length is the len argument
StringData(string) → returns a ptr to the underlying bytes of the string argument

🕵️‍♂️ Where Does unsafe Actually Live?

If you explore the Go source code, you’ll find the unsafe package in the root of the src directory. Inside it, there’s only one file — unsafe.go — and its content (as of Go 1.25.0) looks like this:

package unsafe
type ArbitraryType int

type IntegerType int
type Pointer *ArbitraryType
func Sizeof(x ArbitraryType) uintptr
func Offsetof(x ArbitraryType) uintptr
func Alignof(x ArbitraryType) uintptr
func Add(ptr Pointer, len IntegerType) Pointer

func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType

func SliceData(slice []ArbitraryType) *ArbitraryType
func String(ptr *byte, len IntegerType) string
func StringData(str string) *byte

So… where are the implementations? 🤔
There’s no .s (Go assembly) file in the unsafe directory, and no //go:linkname directives either.
How does Go even make this work if there’s no implementation file or linker trick? (check here if you don't know what I am talking about)

The answer is: unsafe is special to the compiler.
It has hardcoded logic that recognizes the unsafe package and its functions.
When the compiler sees calls like unsafe.Sizeof(), it doesn’t look for an implementation — it directly generates the corresponding code itself.

In other words, the compiler contains special-case logic such as:

“If this is unsafe.Sizeof, compute the size at compile time.”
“If this is unsafe.Pointer, treat it as a type conversion.”

These functions are compiler intrinsics — they don’t execute at runtime, they’re evaluated during compilation.

For example, inside src/cmd/compile/internal/typecheck/universe.go, you can see how the unsafe functions are registered alongside the built-in functions (len, recover, new, panic, etc.) and other predeclared names in Go (_, true, false, nil, and so on).
It is done by calling the function, called NewBuiltin(for the functions), which is documented as:

// NewBuiltin returns a new Name representing a builtin function,
// either predeclared or from package unsafe.

So the compiler knows exactly what each of these functions means — not because they’re implemented in Go or assembly, but because they’re baked directly into the compiler itself.

For more information about it, you may check:
cmd/compile/internal/ssagen/ssa.go
cmd/compile/internal/typecheck/universe.go
cmd/compile/internal/ir/name.go

😈 Fun with `unsafe`: Dangerous but Cool

I love playing with unsafe. It helps me understand Go’s memory model better — and honestly, it’s just fun. Sometimes it even leads to real-world performance optimizations that are impossible with normal Go code.

The unsafe package is fascinating in every language, but I especially enjoy how Rust handles it — its unsafe blocks let you do things like memory unions, where two variables can share the exact same memory space(like C/C++), something that is not possible in Go as Dave Cheney explained, but unsafe still gives us plenty of ways to peek behind the curtain.

Some fun and useful experiments you can try:

Access the fields of a struct by manually moving the Pointer
Explore built-in Go types and peek inside their internals (like inspecting the buckets of a map)
Or some common optimizations like convert string to bytes, which normally cause allocation, but with unsafe, you can do it without triggering any allocations

Let's see some examples:

1- Accessing the fields of a struct with `unsafe`


type Car struct {
    Name string
    year int
}

func main() {
    c := Car{
        Name: "BMW",
        year: 2023,
    }
    cPTR := unsafe.Pointer(&c)
    name := *(*string)(cPTR)
    fmt.Println("Name:", name)
    year := *(*int)(unsafe.Add(cPTR, unsafe.Offsetof(Car{}.year)))
    fmt.Println("Year:", year)
    *(*int)(unsafe.Add(cPTR, unsafe.Offsetof(Car{}.year))) = 2024
    fmt.Println("updated car", c)
}

Notes:

In name := *(*string)(cPTR) we are saying that the cPTR is actually *string and then dereference it with *, so it is not something really hard, it is just a simple type cast for unsafe.Pointer.
Structs in Go are nothing but their fields, so when we take the unsafe.Pointer of the struct, we are already pointing at the first field.
Each type has a size, read here, but for structs, it’s safer to use unsafe.Offsetof() because of potential padding.
In this example, we could skip unsafe.Offsetof() since the layout is predictable on a 64-bit system: the string takes 16 bytes (two machine words), and the int takes 8 bytes, so there’s no padding - meaning we could do with just 16 instead of unsafe.Offsetof(Car{}.year).

2- Explore the builtin Go types

    y := map[string]string{
        "s":  "s",
        "rr": "rr",
    }

    yPTR := (*unsafe.Pointer)(unsafe.Pointer(&y))
    count := *(*int64)(*yPTR)
    flag := *(*uint8)(unsafe.Add(*yPTR, unsafe.Offsetof(hmap{}.flags)))
    B := *(*uint8)(unsafe.Add(*yPTR, unsafe.Offsetof(hmap{}.B)))
    bucketsPTR := *(*unsafe.Pointer)(unsafe.Add(*yPTR, unsafe.Offsetof(hmap{}.buckets)))
    oldBucketsPTR := *(*unsafe.Pointer)(unsafe.Add(*yPTR, unsafe.Offsetof(hmap{}.oldbuckets)))

    fmt.Println("flags:", flag)
    fmt.Println("B:", B)
    fmt.Println("buckets:", bucketsPTR)
    fmt.Println("oldbuckets:", oldBucketsPTR)
    fmt.Println("count:", count)

    key := unsafe.Add(bucketsPTR, 8)
    value := unsafe.Add(bucketsPTR, 24)
    key2 := unsafe.Add(bucketsPTR, 40)
    value2 := unsafe.Add(bucketsPTR, 56)

    *(*string)(value2) = "changed"

    fmt.Println(*(*string)(key), *(*string)(value))
    fmt.Println(*(*string)(key2), *(*string)(value2))

A little simplified version of hmap looks like this:

type hmap struct {
    count     int 
    flags     uint8
    B         uint8  
    noverflow uint16 
    hash0     uint32 

    buckets    unsafe.Pointer 
    oldbuckets unsafe.Pointer 
    nevacuate  uintptr        
    clearSeq   uint64
}

Notes

We are exploring Maps here (no_swiss).
Maps are pointers to the hmap struct, so in the line yPTR := (*unsafe.Pointer)(unsafe.Pointer(&y)) we are telling that the yPTR is actually a pointer to the unsafe.Pointer, because the y is a pointer itself and the &y is something like a pointer-to-pointer.
In line count := *(*int64)(*yPTR) we are already at the field count.
We move until we get to the buckets where the data is actually stored.
Each Bucket has a tophash that helps it search faster (it filters candidate buckets before comparing keys), the tophash is [8]uint8, so to reach the first key we should key := unsafe.Add(bucketsPTR, 8).
Each string is 16bytes, so for the first value we should move (8+16)24bytes and same for others.
As you see, we can also edit the map, and we can also do other funny things like accessing the old buckets to see the overflows and more, maybe change the map to the threshold and see what is going on in the buckets, discussed about it here

I suggest you do the same things with the channels, there you can access the goroutines and many more fun things.

3- A common simple optimization is to convert `string` to `bytes`, which has one allocation normally

    stringTest := "hello"

    stringTestByte := *(*[]byte)(unsafe.Pointer(&stringTest))
    fmt.Println(stringTestByte)     // Same output as the next line
    fmt.Println([]byte(stringTest)) // But this version allocates

As explained here, strings are pointers to underlying bytes + len, so when we take the unsafe.Pointer of the string, in the StringHeader struct we are actually pointing at the first field, which is the underlying bytes ( here you can move 8 more and get the len, I know you are the best at doing these now 😉)

The unsafe package is both powerful and risky — a bit like playing with fire 🔥. It’s great for learning, debugging, squeezing out performance, and some low-level codes — but keep it out of production code unless you really know what you’re doing.

Just remember: with unsafe, you’re responsible for safety now.

🛠️Golang Source Code Essentials, Part 0: Compiler Directives & Build Tags⚡

arshia_rgh — Thu, 25 Sep 2025 21:41:25 +0000

After the Go Maps Deep Dive (no_swiss) — Part 1, the natural next step is to explore Go’s source code itself and see how these functionalities are actually implemented under the hood.

But before we can dive into files like map.go or map_swiss.go, we need to equip ourselves with some background knowledge. The Go runtime makes heavy use of compiler directives, unsafe operations, bit tricks, and even bits of assembly. Without understanding these essentials, the source code can feel cryptic.

That’s why I’m starting this new series: Golang Source Code Essentials. This series will serve as a foundation, teaching the tools and concepts you’ll repeatedly encounter when reading Go’s internals. Once we cover these, we’ll return to maps (and beyond!) with the confidence to truly understand what’s happening in the runtime.

We’ll cover:

⚡Compiler directives (//go:linkname, //go:nosplit, build tags, etc.)

🔒Unsafe and how to use

🔢Bit operations and low-level optimizations commonly used in the runtime

🧩Assembly touchpoints (memmove, memclrNoHeapPointers, etc.)

📏Stack growth and garbage collector interactions (why nosplit matters)

🧭Practical tips on navigating, modifying, and rebuilding the Go source

By the end of this series, you’ll be comfortable opening Go’s runtime files and actually understanding what’s happening.

For part 0, we start with Compiler Directives and Build tags

Line Directives (`//line`)📝:

Mainly used by code generators and tools to improve error reporting, it tells the compiler to treat the following code as if it comes from a different line number and/or file.

example:

//line main.go:100
var x = "test" + 123

Here, regardless of the actual file or line, the compiler output will look like::

main.go:100: invalid operation: "test" + 123 (mismatched types untyped string and untyped int)

Function Directives⚙️:

1. //go:noescape:

It tells the compiler that the function does not allow any of its pointer arguments to escape to the heap. This can help the compiler optimize stack allocation and calling conventions. It is mainly used in low-level or runtime code, and has no effect on the function's behavior—just on how the compiler treats pointer arguments.

It must be followed by a function declaration without a body, and the .s assembly file must exist in the same package; otherwise, the code won’t compile.

example:

//go:noescape
func test1(a unsafe.Pointer) unsafe.Pointer

This is valid if there is the .s file (Go assembly source file, we will talk about these in the next parts) and the actual implementation of the test1 is inside that .s file with the exact same name, for example:

//go:build amd64

#include "textflag.h"

// TEXT ·test1(SB), NOSPLIT, $0-16
// Implements: func test1(a unsafe.Pointer) unsafe.Pointer
TEXT ·test1(SB), NOSPLIT, $0-16
    MOVQ 0(FP), AX      // load a
    MOVQ AX, 8(FP)      // store return value
    RET

in the first line you can see that //go:build amd64, this is a build constraint. It tells the Go build system to compile that file only when targeting the amd64 architecture, If the file name already ends with _amd64.s, the build tag is optional

if we don't have any .s files in the same package and run the above code we will get the error: missing function body.

As I mentioned, functions marked with //go:noescape must not have a body.

we put a .s file and run the following code:

//line main.go:100
//var x = "test" + 123

//go:noescape
func test1(a unsafe.Pointer) unsafe.Pointer

//go:noescape
func test2(a unsafe.Pointer) unsafe.Pointer {
    return test1(a)
}

The output will be:

main.go:106: can only use //go:noescape with external func implementations

( Have you noticed the main.go:106!!!?, Very cool, isn't it?!🤩 )

2. //go:noinline🚫:

It must be followed by a function declaration, telling the compiler to never inline the immediately following function, regardless of size or heuristics. It is used mainly for writing stable benchmarks (preventing the optimizer from removing or folding calls) or debugging the compiler

//go:noinline
func add(a, b int) int {
    return a + b
}

3. //go:nosplit🧵:

It must be followed by a function declaration, disables stack growth checks for the immediately following function. The compiler omits the stack-splitting prologue, so the function must never need more stack than is already available ( no call to morestack ). Used in tiny, leaf, low-level runtime functions that must run even when the goroutine stack is almost exhausted (e.g. during stack growth, signal handling).

Note: We will discuss this further in later parts.

Constraints: keep it very small, do not call into code that might allocate, panic, block, or grow the stack. Misuse can cause unrecoverable crashes.

//go:nosplit
func load8(p unsafe.Pointer) uint8 {
    // Must stay tiny: just one load.
    return *(*uint8)(p)
}

Crash example:

//go:nosplit
func add(n int) int {
    if n == 0 {
        return 0
    }
    return 1 + add(n-1)
}

I called it with n = 1000 and the output was:

main.add: nosplit stack over 792 byte limit
main.add<1>
    grows 24 bytes, calls main.add<1>
    infinite cycle

Linkname Directives(`//go:linkname`)🔗:

It tells the compiler that a local identifier should be bound to (share the symbol of) some other (possibly unexported) identifier in another package.

It bypasses visibility, is inherently unsafe and version‑fragile.

It requires importing the unsafe package, even if unused (e.g. import _ "unsafe"), because the Go team specifically tell us that this is unsafe

The two functions that are linked together don’t need to have the same signature, leading to panics if misused

example:


// inside the main.go file:

//go:linkname testLink
func testLink(a, b, c string) string

func main() {
    log.Println(testLink("a", "b", "c"))
}


// inside the test.go file in another package named 'another':
//go:linkname test main.testLink
func test(a, b string) string {
    return a + b
}

The output will be "ab". As you can see, the test function in the another package is private (not exported), and the signatures also don’t match.

- Linkname: Dangerous Freedom⚠️

The linkname directive created a problem: we can easily write functions or variables that link to Go’s internals, and this made many dependencies on the Golang internals, this has created a serious problem: many programs now depend on Go’s internal details, something they were never meant to rely on, because changing the internals may break those Go programs as well, The Go team is trying to lock down (or at least limit) the usage of linkname in user code to avoid more dependencies on the Golang internals, and currently Go team has a hall of shame that includes some most known programs that are already dependent on these internals for example:

// Call from Go to C.
//
// This must be nosplit because it's used for syscalls on some
// platforms. Syscalls may have untyped arguments on the stack, so
// it's not safe to grow or scan the stack.
//
// cgocall should be an internal detail,
// but widely used packages access it using linkname.
// Notable members of the hall of shame include:
//   - github.com/ebitengine/purego
//
// Do not remove or change the type signature.
// See go.dev/issue/67401.
//
//go:linkname cgocall
//go:nosplit
func cgocall(fn, arg unsafe.Pointer) int32 {

}

As you can see, there is documentation for this function inside cgocall.go file inside the runtime package and includes a Notable members of the hall of shame list.

I strongly recommend reading the Russ Cox issue in Golang GitHub page: cmd/link: lock down future uses of linkname #67401

Build Tags (`//go:build`, `// +build`)🏗️:

Build tags determine whether a file should be included in the compilation of a package. This is incredibly useful for writing platform-specific code or creating different build versions of your application.

The modern and preferred syntax is the //go:build directive. It must be placed at the top of the file, preceded only by blank lines or other comments, and must be followed by a blank line.

//go:build (Go 1.17+) This means compile this file only when building for Linux on amd64:

//go:build linux && amd64

This means compile this file only on 64-bit Linux or 64-bit Windows systems.

//go:build (linux && amd64) || (windows && amd64)

Custom Tags🏷️: You can define your own tags to create different builds, like a "development" build with extra logging.

//go:build dev

package mypackage

import "log"

func DebugLog(message string) {
    log.Printf("[DEV] %s", message)
}

//go:build !dev

package mypackage

// This is a no-op in release builds.
func DebugLog(message string) {}

To compile with the dev tag, you use the -tags flag:

# This will include debug_logger.go and its DebugLog implementation.
go build -tags="dev"

# This will include release_logger.go, where DebugLog does nothing.
go build

// +build (Legacy) This is the older syntax. While still supported, //go:build is preferred. You can use both in the same file for backward compatibility. A file is included if the boolean formula is satisfied.

// +build linux,darwin
// ... this file will be included on Linux OR Darwin systems.

🚀What’s Next?

In this part, we explored compiler directives and build tags, the “hidden switches” that control how Go source files are compiled and how runtime functions behave. These are everywhere in the Go runtime and now you’ll recognize them when diving into files like runtime/asm_amd64.s or map.go.

👉 In Part 1, we’ll dive into the Unsafe & Internal Packages that the runtime depends on. You’ll see how unsafe.Pointer, runtime/internal/sys, and runtime/internal/atomic unlock the low-level power behind Go.

Stay tuned — it’s about to get even more interesting! ⚡

🗺️ Go Maps Deep Dive (no_swiss) — Part 1: The Secrets Behind O(1) Performance, Overflows, and Growth

arshia_rgh — Wed, 17 Sep 2025 11:23:16 +0000

Note: This article focuses on the old Go map implementation (map_noswiss). In later parts of this series, we will also cover the Swiss map (map_swiss).

Welcome back to our deep dive into Go maps! 👋 In the first part of this series, we covered the basics of what Go maps are, their properties, and how to use them. Now, it's time to go deeper and uncover the magic that makes maps so efficient. 🗺️✨

In this article, we'll explore the inner workings of Go maps to understand:

Why map operations are usually O(1) and what can affect this performance. ⏱️
How Go handles hash collisions with "overflow" buckets. 📦➡️📦
The clever way maps grow without bringing your application to a halt. 🌱
The role of a unique "seed" in the hashing process. 🎲

Let's get started!

The O(1) Magic: It's All About Hashing

You've probably heard that map lookups, insertions, and deletions are O(1) operations, meaning they take constant time on average, regardless of the number of elements in the map. But how is this possible? The secret lies in hashing. 🔑➡️🔢

When you add a key-value pair to a map, Go uses a hash function to convert the key into a number. This number, or "hash," is then used to determine which "bucket" the key-value pair should be stored in. A bucket is essentially a small, fixed-size array that can hold a few key-value pairs.

Because the hash function is designed to be very fast and to distribute keys evenly across the available buckets, Go can quickly locate the correct bucket for a given key without having to check every element in the map. This is what gives maps their O(1) performance. 💪

However, I said usually O(1). What happens when two different keys generate the same hash? This is called a hash collision, and it can slightly degrade performance. We'll explore this more in the section on overflows. 💥

The Unique Seed: Why the Same Key Can Live in Different Places

Here's a fun fact that might surprise you: if you create two different maps and insert the same key into both, that key might end up in different buckets in each map. 🤯

Why? Because every new map in Go is created with a unique random seed. This seed is used in the hashing algorithm, which means that the hash generated for a key is unique to that specific map instance.

Let's look at an example:

package main

import "fmt"

func main() {
    map1 := make(map[string]int)
    map2 := make(map[string]int)

    map1["a"] = 1
    map2["a"] = 1

    // The internal location of "a" in map1 and map2
    // will likely be different!
}

This randomization is a security feature that helps prevent a type of attack called "hash-flooding," where an attacker could craft keys that all hash to the same bucket, effectively turning the map's O(1) operations into O(n) and slowing down your application. 🛡️

When Buckets Get Full: The Role of Overflows

Each bucket in a Go map can hold up to 8 key-value pairs. But what happens when more than 8 keys hash to the same bucket? Go doesn't just give up. Instead, it creates an overflow bucket and links it to the original bucket. 🔗

A simplified visualization of a hash table bucket with an overflow bucket attached, showing keys spilling into the overflow when the primary bucket is full.

If you have many keys that hash to the same bucket, you can end up with a chain of overflow buckets. When looking up a key in this scenario, Go first checks the main bucket and then has to traverse the chain of overflow buckets. This is one of the reasons why map operations are not always O(1). In the worst-case scenario (many collisions), a lookup could degrade to O(n) performance, where 'n' is the number of items in the bucket and its overflows. 🐢

The Growing Map: An Incremental Approach

As you add more and more elements to a map, it will eventually need to grow to accommodate the new data and maintain its performance. A map in Go will trigger a growth cycle in one of two situations:

The load factor is too high:

If the average number of elements per bucket exceeds a certain threshold (currently around 6.5), the map will grow. 📈

Too many overflow buckets:

If the map has too many overflow buckets, it's a sign that the keys are not well-distributed, and a resize is needed to spread them out more evenly. 🧹

But how does this growth happen? If you have a map with thousands or even millions of key-value pairs, resizing it all at once could cause a noticeable pause in your application. To avoid this, Go employs a clever strategy: incremental growth. 🚀

When a map needs to grow, Go allocates a new, larger array of buckets (usually double the size of the old one). However, it doesn't copy all the data over at once. Instead, the copying happens gradually. Each time you write to or delete from the map, Go moves a few buckets from the old array to the new one. ➡️➡️➡️

This incremental approach spreads the work of resizing over time, ensuring that no single map operation takes too long. It's a fantastic example of how Go is designed for building responsive, low-latency applications. 💖

🗝️About the hint in make(map[K]V, hint)

When you write something like:

x := make(map[int]int, 13)

the second argument (13 in this case) is not the length, size, or capacity of the map. It is just a hint to the runtime about how many elements you expect to insert.

Go maps use buckets internally, and the runtime uses the hint to decide how many buckets to preallocate. Each bucket can hold up to 8 key/value pairs. Go tries to keep the average load factor around 6.5 elements per bucket before growing.

For example,

With a hint of 13, the runtime will start with 2 buckets (capacity for 16 slots). Since 13 / 2 = 6.5, this is right at the threshold.
If the hint were 14, the runtime would start with 4 buckets (capacity for 32 slots). That’s because 14 / 2 = 7 would exceed the load factor limit, so it doubles the bucket count.

This is why the hint value causes jumps in allocation instead of scaling smoothly.

take a look at this table:

Hint Range	Bucket Count	Capacity
0 – 8	1	8
9 – 13	2	16
14 – 26	4	32
27 – 52	8	64
53 – 104	16	128
105 – 208	32	256
209 – 416	64	512
417 – 832	128	1024
833 – 1664	256	2048

What's Next?

We've covered a lot of ground in this article, from hashing and overflows to the incremental growth of maps. I hope you now have a better appreciation for the sophisticated engineering that makes Go maps so powerful and efficient. 🧠💡

But we're not done yet! In the next part of this series, we'll get our hands dirty and dive into the Go source code to see exactly how all of these concepts are implemented. It's going to be a fun and enlightening journey, so stay tuned! 💻🔍

🗺️ Go Maps Deep Dive — Part 0: Understanding the Basics

arshia_rgh — Tue, 09 Sep 2025 14:23:18 +0000

Note: Most of the details in this article apply to both the old and new Go map implementations (map_noswiss and map_swiss). However, when I refer to a map as a pointer to hmap, that specifically applies to the old implementation (map_noswiss). In later parts of this series, we will also cover the Swiss maps.

Series Intro:

Welcome to the start of my Go maps deep-dive series!
In the upcoming parts, we’ll go from the outer layer of maps to their deep internals — how they’re implemented under the hood, memory layout, hash functions, optimizations, and performance tricks.
This is Part 0, where we’ll start from the basics: what maps are, how they behave, and what you should know before diving deeper.

🧩 What Are Maps?

In Go, a map is a key-value data structure.
If you’ve used Rust, you know it as a HashMap.
If you’ve used Python, you know it as a dict.

m := map[string]int{
    "apple":  5,
    "orange": 3,
}
fmt.Println(m["apple"]) // 5

They’re unordered collections of key-value pairs, designed for fast lookups and inserts.

🗝️ Maps Are Pointers

Unlike slices, maps in Go are internally pointers to a data structure called hmap.
This has two important consequences:

You don’t need to pass them by pointer.
When you pass a map to a function, you’re already passing a pointer under the hood. ( in old versions you were used to do like *map[int]int but changed) see Lan Taylor

In the very early days what we call maps now were written as pointers, so you wrote *map[int]int. We moved away from that when we realized that no one ever wrote map without writing *map.

The zero value is nil.

var m map[string]int
fmt.Println(m == nil) // true

if you declare a map and then assign it to the new value the both m1, and m2 will be placed in unique memory locations (see blog by dave chenny There is no pass-by-reference in Go) and them value both will be the address of a same hmap structure.
Actually the m1 will be cpoied to the m2 (like all assigns in Golang)
Updating m2 also updates m1.

m1 := make(map[string]int)
m2 := m1

Diagram: m1 and m2 point to the same underlying hmap struct ( picture by VictoriaMetrics )

⚖️ Maps Are Not Comparable

Unlike slices, you cannot compare two maps directly:

m1 := map[string]int{}
m2 := map[string]int{}

// This will not compile ❌
if m1 == m2 {}

// This will not compile too ❌
if m1 == m1 {}

// But you *can* check if a map is nil ✅
if m1 == nil {
    fmt.Println("m1 is nil")
}

🔑 Keys Must Be Comparable

The type you use as a key must be comparable in Go.

✅ Valid keys:

string
int, float64
struct (if all fields are comparable)

❌ Invalid keys:

slice
map
function

interface{} or any can be sometimes ok sometimes nok:

var x, x2 map[interface{}]int

x["a"] = 1 // OK✅

x2[[]int{1, 2}] = 1 //runtime panic!❌

⏱️ Lookup and Insert Are Usually O(1)

Go maps are hash-based, so operations like searching and inserting are on average O(1):

Why “usually” O(1)?
In upcoming parts, we’ll explore hash collisions, buckets, and why performance can sometimes degrade. Stay tuned! 👀

⚡ Maps Are Not Thread-Safe

Go maps are not safe for concurrent writes.
If you try, you’ll get a fatal runtime error:

m := map[int]int{}
go func() { m[1] = 42 }()
go func() { m[2] = 84 }()

💥 Runtime panic: concurrent map writes

🏗️ Creating Maps with make

You can create maps with make:

m := make(map[int]int, 10)

Here, the 10 is not the length — it’s a hint to Go about the expected size.
This helps reduce resizing overhead when inserting many items.

We’ll talk about why it’s just a hint and how Go actually allocates buckets in a future part.

🔜 What’s Next?

This is just the beginning! In Part 1, we’ll start peeling back the layers of the hmap structure — the backbone of Go maps.
We’ll cover:

The internal hmap struct
Buckets and hashing
Load factors and resizing strategies

and after all parts you will have good sight about what happening exactly inside the go internals for maps

Stay tuned — things are about to get really interesting! 🚀

Forem: arshia_rgh

🧩Golang Type Memory Representation Quick Reference

Pointer

String

Int, Float, complex(real + imaginary floats) or uint

Slice

Map

Chan

Struct

Interface

Func

🛠️ Golang Source Code Essentials, Part 1: The unsafe Package — Breaking Go’s Safety for Power

⚙️ Why the Runtime Needs Unsafe Power

🧠 Core Functions and Types in the unsafe Package

🧩 The Core Types

⚖️ The Utility Functions

🕵️‍♂️ Where Does unsafe Actually Live?

😈 Fun with unsafe: Dangerous but Cool

1- Accessing the fields of a struct with unsafe

2- Explore the builtin Go types

3- A common simple optimization is to convert string to bytes, which has one allocation normally

🛠️Golang Source Code Essentials, Part 0: Compiler Directives & Build Tags⚡

Line Directives (//line)📝:

Function Directives⚙️:

1. //go:noescape:

2. //go:noinline🚫:

3. //go:nosplit🧵:

Linkname Directives(//go:linkname)🔗:

Build Tags (//go:build, // +build)🏗️:

🚀What’s Next?

🗺️ Go Maps Deep Dive (no_swiss) — Part 1: The Secrets Behind O(1) Performance, Overflows, and Growth

The O(1) Magic: It's All About Hashing

The Unique Seed: Why the Same Key Can Live in Different Places

When Buckets Get Full: The Role of Overflows

The Growing Map: An Incremental Approach

🗝️About the hint in make(map[K]V, hint)

What's Next?

🗺️ Go Maps Deep Dive — Part 0: Understanding the Basics

Series Intro:

🧩 What Are Maps?

🗝️ Maps Are Pointers

⚖️ Maps Are Not Comparable

🔑 Keys Must Be Comparable

⏱️ Lookup and Insert Are Usually O(1)

⚡ Maps Are Not Thread-Safe

🏗️ Creating Maps with make

🔜 What’s Next?

⚙️ Why the Runtime Needs `Unsafe` Power

🧠 Core Functions and Types in the `unsafe` Package

😈 Fun with `unsafe`: Dangerous but Cool

1- Accessing the fields of a struct with `unsafe`

3- A common simple optimization is to convert `string` to `bytes`, which has one allocation normally

Line Directives (`//line`)📝:

Linkname Directives(`//go:linkname`)🔗:

Build Tags (`//go:build`, `// +build`)🏗️: