pool

func Configure ¶

func Configure(config PoolConfig)

Configure sets global pool configuration.

This function should be called once during application initialization, before any pooled objects are allocated. Calling it multiple times will reinitialize all pools, which may cause temporary allocation spikes.

Parameters:

• config: Pool configuration with Enabled and MaxSize settings

Example 1 - Production Setup:

func main() {
	// Configure pooling early
	pool.Configure(pool.PoolConfig{
		Enabled: true,
		MaxSize: 1000,
	})

	// Now start your application
	server.Start()
}

Example 2 - Disable for Debugging:

// Disable pooling to detect memory leaks
pool.Configure(pool.PoolConfig{
	Enabled: false, // All Get/Put operations become no-ops
})

Example 3 - Memory-Constrained Environment:

// Reduce pool size for low-memory systems
pool.Configure(pool.PoolConfig{
	Enabled: true,
	MaxSize: 100, // Keep fewer objects
})

Performance Impact:

• Enabling pooling: 50-70% reduction in allocations
• Disabling pooling: Easier debugging, higher GC pressure
• MaxSize too low: More allocations (pool fills up)
• MaxSize too high: More memory usage

Thread Safety:

Not thread-safe. Call only during initialization.

func GetByteBuffer ¶

func GetByteBuffer() []byte

GetByteBuffer returns a byte buffer from the pool.

The returned buffer has length 0 but pre-allocated capacity (typically 1KB). Use this for temporary byte operations like encoding, serialization, or building binary data. Always call PutByteBuffer when done.

Returns:

• Empty byte slice with capacity 1024

Example 1 - JSON Encoding:

func encodeJSON(data interface{}) ([]byte, error) {
	buf := pool.GetByteBuffer()
	defer pool.PutByteBuffer(buf)

	encoder := json.NewEncoder(bytes.NewBuffer(buf))
	if err := encoder.Encode(data); err != nil {
		return nil, err
	}

	// Return a copy (original goes back to pool)
	result := make([]byte, len(buf))
	copy(result, buf)
	return result, nil
}

Example 2 - Binary Protocol:

func encodeMessage(msgType byte, payload []byte) []byte {
	buf := pool.GetByteBuffer()
	defer pool.PutByteBuffer(buf)

	// Write header
	buf = append(buf, msgType)
	buf = binary.BigEndian.AppendUint32(buf, uint32(len(payload)))

	// Write payload
	buf = append(buf, payload...)

	return append([]byte(nil), buf...) // Return copy
}

Example 3 - Hash Computation:

func computeHash(data string) []byte {
	buf := pool.GetByteBuffer()
	defer pool.PutByteBuffer(buf)

	h := sha256.New()
	h.Write([]byte(data))
	return h.Sum(buf[:0]) // Use buf as backing array
}

Performance:

• Eliminates allocation for temporary buffers
• Pre-allocated 1KB handles most use cases
• Grows automatically if needed

func GetInterfaceSlice ¶

func GetInterfaceSlice() []interface{}

GetInterfaceSlice returns an interface slice from the pool.

The returned slice has length 0 but pre-allocated capacity (typically 16). Use this for building lists of mixed-type values like query result rows. Always call PutInterfaceSlice when done.

Returns:

• Empty interface slice with capacity 16

Example 1 - Build Result Row:

func buildRow(id int, name string, active bool) []interface{} {
	row := pool.GetInterfaceSlice()
	defer pool.PutInterfaceSlice(row)

	row = append(row, id, name, active)

	// Return a copy
	return append([]interface{}(nil), row...)
}

Example 2 - Collect Values:

func extractValues(props map[string]interface{}, keys []string) []interface{} {
	values := pool.GetInterfaceSlice()
	defer pool.PutInterfaceSlice(values)

	for _, key := range keys {
		if val, ok := props[key]; ok {
			values = append(values, val)
		}
	}

	return append([]interface{}(nil), values...)
}

Example 3 - Function Arguments:

func callFunction(name string, args ...interface{}) interface{} {
	argList := pool.GetInterfaceSlice()
	defer pool.PutInterfaceSlice(argList)

	argList = append(argList, args...)

	return functions[name](argList...)
}

Performance:

• Eliminates allocation for slice header
• Pre-allocated capacity 16 handles most rows
• Typical savings: 1 allocation per call

func GetMap ¶

func GetMap() map[string]interface{}

GetMap returns a string-to-interface map from the pool.

The returned map is empty and ready to use. Maps are commonly used for query parameters, node properties, and JSON-like data structures. Always call PutMap when done to return it to the pool.

Returns:

• Empty map with capacity 8

Example 1 - Query Parameters:

func buildParams(userID string, filters map[string]string) map[string]interface{} {
	params := pool.GetMap()
	defer pool.PutMap(params)

	params["userID"] = userID
	for k, v := range filters {
		params[k] = v
	}

	// Return a copy
	result := make(map[string]interface{}, len(params))
	for k, v := range params {
		result[k] = v
	}
	return result
}

Example 2 - Node Properties:

func createNode(id, name string, age int) *Node {
	props := pool.GetMap()
	defer pool.PutMap(props)

	props["id"] = id
	props["name"] = name
	props["age"] = age
	props["created_at"] = time.Now()

	return &Node{Properties: copyMap(props)}
}

Example 3 - JSON Response:

func buildResponse(status string, data interface{}) map[string]interface{} {
	resp := pool.GetMap()
	defer pool.PutMap(resp)

	resp["status"] = status
	resp["data"] = data
	resp["timestamp"] = time.Now().Unix()

	return copyMap(resp)
}

Performance:

• Eliminates allocation for map header and initial buckets
• Pre-allocated capacity 8 handles most use cases
• Typical savings: 1 allocation per call

func GetRowSlice ¶

func GetRowSlice() [][]interface{}

GetRowSlice returns a row slice from the pool for query results.

The returned slice has length 0 but may have pre-allocated capacity (typically 64). This reduces allocations when building query result sets. Always call PutRowSlice when done to return the slice to the pool.

Returns:

• Empty slice with pre-allocated capacity if pooling is enabled
• Fresh slice with capacity 64 if pooling is disabled

Example 1 - Basic Usage:

rows := pool.GetRowSlice()
defer pool.PutRowSlice(rows)

// Build result set
for _, record := range records {
	row := []interface{}{record.ID, record.Name, record.Value}
	rows = append(rows, row)
}

return rows

Example 2 - Query Execution:

func executeQuery(query string) ([][]interface{}, error) {
	rows := pool.GetRowSlice()
	defer pool.PutRowSlice(rows)

	// Execute query and populate rows
	results := db.Query(query)
	for results.Next() {
		var id, name, value interface{}
		results.Scan(&id, &name, &value)
		rows = append(rows, []interface{}{id, name, value})
	}

	// Make a copy to return (original goes back to pool)
	result := make([][]interface{}, len(rows))
	copy(result, rows)
	return result, nil
}

Example 3 - Batch Processing:

// Process 10,000 records with minimal allocations
for batch := range batches {
	rows := pool.GetRowSlice()

	for _, record := range batch {
		rows = append(rows, record.ToRow())
	}

	processBatch(rows)
	pool.PutRowSlice(rows) // Reuse for next batch
}

Performance:

• Eliminates allocation for slice header and backing array
• Typical savings: 2-3 allocations per query
• For 1000 QPS: ~2000-3000 fewer allocations/sec

Memory Safety:

• Returned slice is empty (len=0) but has capacity
• Safe to append without initial allocation
• Don't modify after calling PutRowSlice

ELI12:

Imagine you're doing homework and need scratch paper:

• GetRowSlice: Grab a blank sheet from the recycling bin (pool)
• Use it: Write your work on the paper (append rows)
• PutRowSlice: Erase it and put it back in the bin for next time
• This is faster than getting new paper from the store every time!

func GetStringSlice ¶

func GetStringSlice() []string

GetStringSlice returns a string slice from the pool.

The returned slice has length 0 but pre-allocated capacity (typically 16). Use this for building lists of strings like labels, column names, or tags. Always call PutStringSlice when done.

Returns:

• Empty string slice with capacity 16

Example 1 - Collect Labels:

func getNodeLabels(node *Node) []string {
	labels := pool.GetStringSlice()
	defer pool.PutStringSlice(labels)

	for _, label := range node.Labels {
		if isActive(label) {
			labels = append(labels, label)
		}
	}

	return append([]string(nil), labels...) // Return copy
}

Example 2 - Build Column Names:

func getColumns(fields []Field) []string {
	cols := pool.GetStringSlice()
	defer pool.PutStringSlice(cols)

	for _, field := range fields {
		cols = append(cols, field.Name)
	}

	return append([]string(nil), cols...)
}

Example 3 - Parse Tags:

func parseTags(input string) []string {
	tags := pool.GetStringSlice()
	defer pool.PutStringSlice(tags)

	for _, tag := range strings.Split(input, ",") {
		tag = strings.TrimSpace(tag)
		if tag != "" {
			tags = append(tags, tag)
		}
	}

	return append([]string(nil), tags...)
}

Performance:

• Eliminates allocation for slice header
• Pre-allocated capacity avoids growth for small lists
• Typical savings: 1 allocation per call

func IsEnabled ¶

func IsEnabled() bool

IsEnabled returns whether pooling is enabled.

This function can be used to check if pooling is active, which is useful for conditional logic or debugging output.

Returns:

• true if pooling is enabled (objects are reused)
• false if pooling is disabled (objects are allocated fresh)

Example:

if pool.IsEnabled() {
	fmt.Println("Object pooling is active")
} else {
	fmt.Println("Object pooling is disabled (debug mode)")
}

Use Case:

// Conditional metrics collection
if pool.IsEnabled() {
	metrics.RecordPoolHit()
} else {
	metrics.RecordAllocation()
}

func PutByteBuffer ¶

func PutByteBuffer(buf []byte)

PutByteBuffer returns a byte buffer to the pool for reuse.

The buffer is cleared (length reset to 0) before being pooled. Very large buffers (capacity > 1MB) are not pooled to prevent memory leaks.

Parameters:

• buf: The buffer to return to the pool (will be cleared)

Example:

buf := pool.GetByteBuffer()
defer pool.PutByteBuffer(buf)

// Use buffer...
buf = append(buf, []byte("data")...)

Memory Safety:

• Buffer is cleared (length set to 0)
• Capacity is preserved for reuse
• Don't use buffer after calling PutByteBuffer
• Buffers >1MB are discarded, not pooled

func PutInterfaceSlice ¶

func PutInterfaceSlice(s []interface{})

PutInterfaceSlice returns an interface slice to the pool for reuse.

The slice is cleared (all references set to nil, length reset to 0) before being pooled. Slices with capacity > MaxSize are not pooled to prevent memory leaks.

Parameters:

• s: The slice to return to the pool (will be cleared)

Example:

row := pool.GetInterfaceSlice()
defer pool.PutInterfaceSlice(row)

row = append(row, 1, "test", true)
// Use row...

Memory Safety:

• All references are set to nil
• Allows GC to collect slice contents
• Don't use slice after calling PutInterfaceSlice

func PutMap ¶

func PutMap(m map[string]interface{})

PutMap returns a map to the pool for reuse.

The map is cleared (all entries deleted) before being pooled. Very large maps (len > MaxSize) are not pooled to prevent memory leaks.

Parameters:

• m: The map to return to the pool (will be cleared)

Example:

params := pool.GetMap()
defer pool.PutMap(params)

params["key"] = "value"
// Use params...

Memory Safety:

• All entries are deleted before pooling
• Allows GC to collect map values
• Don't use map after calling PutMap
• Maps with >MaxSize entries are discarded

func PutNodeSlice ¶

func PutNodeSlice(nodes []*PooledNode)

PutNodeSlice returns a node slice to the pool for reuse.

The slice is cleared (all pointers set to nil) before being pooled to allow garbage collection of the node objects. Slices with capacity > MaxSize are not pooled to prevent memory leaks.

Parameters:

• nodes: The slice to return to the pool (will be cleared)

Example:

nodes := pool.GetNodeSlice()
defer pool.PutNodeSlice(nodes)

// Build node list...
nodes = append(nodes, &pool.PooledNode{ID: "node-1"})

Memory Safety:

• All node pointers are set to nil
• Allows GC to collect node objects
• Don't access nodes after calling PutNodeSlice

ELI12:

Like returning a tray of cups to the cafeteria:

• Empty all the cups first (clear pointers)
• Put the tray back on the stack (return to pool)
• If the tray is too big (cap > MaxSize), throw it away

func PutRowSlice ¶

func PutRowSlice(rows [][]interface{})

PutRowSlice returns a row slice to the pool for reuse.

The slice is cleared (all references set to nil) before being pooled to allow garbage collection of the row contents. Very large slices (capacity > MaxSize) are not pooled to prevent memory leaks.

Parameters:

• rows: The slice to return to the pool (will be cleared)

Example:

rows := pool.GetRowSlice()
defer pool.PutRowSlice(rows) // Always return to pool

// Use rows...
rows = append(rows, []interface{}{1, "test"})

Memory Safety:

• All row references are cleared (set to nil)
• Allows GC to collect row contents
• Don't use the slice after calling PutRowSlice

Size Limits:

• Slices with cap > MaxSize are not pooled (prevents memory leaks)
• Typical MaxSize: 1000 rows
• For larger result sets, consider streaming

ELI12:

Like returning a whiteboard to the classroom:

• First, erase everything on it (clear references)
• Then put it back on the rack (return to pool)
• If it's too big to fit on the rack (cap > MaxSize), throw it away
• Don't try to use the whiteboard after you've returned it!

func PutStringBuilder ¶

func PutStringBuilder(b *PooledStringBuilder)

PutStringBuilder returns a string builder to the pool for reuse.

The builder is automatically reset before being pooled. Very large builders (capacity > 64KB) are not pooled to prevent memory leaks.

Parameters:

• b: The builder to return to the pool (will be reset)

Example:

builder := pool.GetStringBuilder()
defer pool.PutStringBuilder(builder) // Always return to pool

builder.WriteString("temporary string")
return builder.String()

Memory Safety:

• Builder is automatically reset (cleared)
• Don't use the builder after calling PutStringBuilder
• Large builders (>64KB) are discarded, not pooled

func PutStringSlice ¶

func PutStringSlice(s []string)

PutStringSlice returns a string slice to the pool for reuse.

The slice is cleared (length reset to 0) before being pooled. Slices with capacity > MaxSize are not pooled to prevent memory leaks.

Parameters:

• s: The slice to return to the pool (will be cleared)

Example:

labels := pool.GetStringSlice()
defer pool.PutStringSlice(labels)

labels = append(labels, "User", "Active")
// Use labels...

Memory Safety:

• Slice is cleared (length set to 0)
• Capacity is preserved for reuse
• Don't use slice after calling PutStringSlice