Project Overview

Source Files

This page is generated from the following source files:

• readme.md

gofnext is a Go library (version >=1.21) that provides function extension capabilities, primarily focusing on cache decorators similar to Python's functools.cache and functools.lru_cache (readme.md:1-18). The library enables developers to wrap functions with caching layers that are concurrent-goroutine safe, supporting multiple backend storage options including in-memory maps, LRU eviction, Redis, and PostgreSQL. The core value proposition lies in its ability to transparently add caching to any function without modifying the original function logic, significantly improving performance for repeated calls with identical arguments (readme.md:11-16).

Technical Stack

Core Features

The library provides a comprehensive set of features centered around function caching and extension:

• Cache Decorator Support: Wraps functions with 0-3 parameters and optional error returns (readme.md:67-78)
• Concurrent Goroutine Safety: All cache operations are thread-safe by default
• Multiple Cache Backends: Memory (default), LRU, Redis, and PostgreSQL support
• TTL Configuration: Configurable time-to-live for cached values and error results
• Custom Cache Maps: Ability to implement custom cache storage
• Custom Hash Functions: Support for custom key generation logic
• Pointer Address vs Value Hashing: Configurable behavior for pointer parameter handling

Decorator Cases and Usage

The library provides a systematic mapping between function signatures and their corresponding cache decorators:

(readme.md:41-55)

For functions returning errors, the library provides specialized decorators (CacheFn0Err, CacheFn1Err, CacheFn2Err) that handle error caching separately with configurable TTL settings. Configuration options include TTL for successful results (TTL: time.Hour) and separate TTL for error results (ErrTTl), allowing fine-grained control over cache invalidation behavior (readme.md:20-32).

System Architecture

The architecture of gofnext follows a layered decorator pattern where cache functionality is abstracted behind a CacheMap interface, allowing different storage backends to be plugged in transparently.

正在加载图表渲染器...

Architecture Explanation:

1. User Functions Layer: The top layer represents user-defined functions with varying signatures (0-3 parameters, with or without error returns). These functions remain unchanged and are wrapped by decorators.

2. Decorator Layer: Each function signature has a corresponding decorator (CacheFn0 through CacheFn3, plus error variants). Decorators intercept function calls, check cache, and only invoke the original function on cache misses.

3. Configuration Layer: The gofnext.Config struct centralizes all cache behavior settings including TTL values, custom hash functions, and cache backend selection (readme.md:33-39).

4. Backend Layer: Multiple storage implementations conform to the CacheMap interface. Memory is default; LRU provides size-limited eviction; Redis enables distributed caching; PostgreSQL offers persistence.

Evidence Points:

• Decorator case mappings: readme.md:41-55
• Feature list including backend support: readme.md:67-78

Cache Lookup Data Flow

The following sequence diagram illustrates the critical data flow when a cached function is invoked, showing the decision points for cache hit/miss scenarios and error handling:

正在加载图表渲染器...

Data Flow Explanation:

1. Invocation: When a caller invokes the cached function, the decorator intercepts the call before any computation occurs.

2. Key Generation: Arguments are hashed using either the default hash function or a custom implementation configured via gofnext.Config. This handles pointer address vs value hashing behavior (readme.md:37-38).

3. Cache Lookup: The decorator queries the configured CacheMap backend (memory, LRU, Redis, etc.) using the generated key.

4. Cache Hit Path: If a value exists and hasn't expired (based on TTL), the cached value is returned immediately without invoking the original function.

5. Cache Miss Path: On cache miss, the original function executes with the provided arguments. The result is then stored in cache with appropriate TTL (regular TTL for success, ErrTTL for errors) before being returned.

6. Error Handling: Error-returning functions use specialized decorators that cache errors separately, preventing repeated failed calls from hitting the underlying function.

Evidence Points:

• Error cache TTL configuration: readme.md:36
• Cache backend configuration examples: readme.md:52-54

Performance Benchmarks

Performance testing reveals significant improvements when using cache decorators, with memory cache providing approximately 117,000x faster execution compared to uncached calls:

(readme.md:56-65)

Benchmark Analysis:

1. Memory vs LRU Cache: Performance is nearly identical (~100ns/op), with LRU adding minimal overhead for eviction tracking. Both reduce allocations from 99 to 2 per operation.

2. Redis Cache Trade-off: Redis caching is ~780x slower than memory cache due to network round-trips and serialization overhead. However, it still provides ~150x improvement over no cache and enables distributed caching across multiple application instances.

3. Memory Efficiency: Memory and LRU caches reduce memory allocation by ~97% (281KB to 72B per operation), significantly reducing GC pressure in high-throughput scenarios.

4. Use Case Guidance: Memory/LRU caches are ideal for single-instance applications with high call frequency. Redis cache suits distributed systems requiring cache sharing across instances, accepting the latency trade-off.

Evidence Points:

• Complete benchmark results: readme.md:56-65
• Configuration affecting performance: readme.md:41-55

Configuration Options

The gofnext.Config struct provides comprehensive control over cache behavior:

(readme.md:33-39)

Configuration Examples:

go
1// Memory cache with 1-hour TTL
2gofnext.CacheFn0Err(f, &gofnext.Config{TTL: time.Hour})
3
4// LRU cache with max 9999 entries
5gofnext.CacheFn0(f, &gofnext.Config{CacheMap: gofnext.NewCacheLru(9999)})
6
7// Redis cache backend
8gofnext.CacheFn0(f, &gofnext.Config{CacheMap: gofnext.NewCacheRedis("cacheKey")})

(readme.md:52-54)

Applicable Scenarios

The library is particularly well-suited for:

1. Expensive Computations: Functions performing complex calculations, database queries, or API calls that are called repeatedly with the same arguments.

2. Recursive Algorithms: Fibonacci, factorial, and dynamic programming problems where overlapping subproblems exist.

3. Database Query Caching: Reducing database load by caching query results with configurable TTL.

4. Distributed Systems: Using Redis backend to share cache across multiple application instances.

5. Rate-Limited APIs: Caching external API responses to stay within rate limits while serving repeated requests.

Report Reading Roadmap

The following diagram illustrates the recommended reading order for understanding the gofnext library comprehensively:

正在加载图表渲染器...

Reading Path Explanation:

1. Start Here: Project Overview (current page) provides the foundation understanding of library purpose and architecture.

2. Core Concepts: Features and Decorator Usage sections explain the API surface and common patterns.

3. Deep Dive: Configuration and Performance sections cover optimization and tuning.

4. Implementation: For contributors or advanced users needing to understand internal mechanics or implement custom backends.

Quantitative Capabilities

(readme.md:41-55, readme.md:56-65)