Quick Start

Source Files

This page is generated from the following source files:

• go.mod
• examples/decorator_test.go
• examples/decorator-fib_test.go
• examples/decorator-key_test.go
• examples/utils_test.go
• examples/serial_test.go
• examples/decorator-ttl_test.go
• examples/decorator-err_test.go
• examples/decorator-lru_test.go
• examples/decorator-copy_test.go

Environment Requirements

The gofnext library requires Go 1.21.1 or later as specified in the go.mod:3 file. The library has minimal dependencies, primarily relying on github.com/go-redis/redis for optional Redis-based caching and github.com/vmihailenco/msgpack/v5 for serialization (go.mod:6-L8).

Core Dependencies

The library also includes indirect dependencies for testing purposes, including github.com/onsi/ginkgo and github.com/onsi/gomega (go.mod:11-L13).

Installation

Install the gofnext package using the standard Go module system:

bash
1go get github.com/ahuigo/gofnext

This command downloads the library and adds it to the project's go.mod file. The library follows standard Go module practices and integrates seamlessly with existing Go projects.

Importing the Package

After installation, import the package in Go source files:

go
1import "github.com/ahuigo/gofnext"

For serialization utilities, import the serial subpackage:

go
1import "github.com/ahuigo/gofnext/serial"

Evidence: The import statements are demonstrated across multiple example files including examples/decorator_test.go:9 and examples/serial_test.go:8.

Basic Usage Patterns

gofnext provides decorator functions to add caching capabilities to existing functions. The library supports functions with 0, 1, 2, or 3 parameters, as well as variants that return errors.

Zero-Parameter Functions

For functions without parameters, use CacheFn0:

go
1func getUser() UserInfo {
2    time.Sleep(10 * time.Millisecond)
3    return UserInfo{Name: "Alex", Age: 20}
4}
5
6getUserInfoFromDb := gofnext.CacheFn0(getUser)

Evidence: examples/decorator_test.go:12-L18 demonstrates the zero-parameter caching pattern.

Single-Parameter Functions

For functions with one parameter, use CacheFn1:

go
1getUser := func(age int) UserInfo {
2    time.Sleep(10 * time.Millisecond)
3    return UserInfo{Name: "Alex", Age: age}
4}
5
6getUserInfoCached := gofnext.CacheFn1(getUser)

Evidence: examples/decorator_test.go:26-L33 shows single-parameter function caching.

Two-Parameter Functions with Configuration

For functions with two parameters, use CacheFn2 with optional configuration:

go
1getUserScore := func(c context.Context, id int) int {
2    fmt.Println("select score from db where id=", id, time.Now())
3    time.Sleep(10 * time.Millisecond)
4    return 98 + id
5}
6
7getUserScoreWithCache := gofnext.CacheFn2(getUserScore, &gofnext.Config{
8    TTL: time.Hour,
9})

Evidence: examples/decorator_test.go:44-L54 demonstrates two-parameter caching with TTL configuration.

Three-Parameter Functions

For functions with three parameters, use CacheFn3:

go
1sum := func(a, b, c int) int {
2    time.Sleep(10 * time.Millisecond)
3    return a + b + c
4}
5
6sumCache := gofnext.CacheFn3(sum, &gofnext.Config{
7    TTL: time.Hour,
8})

Evidence: examples/decorator_test.go:75-L84 shows three-parameter function caching.

Configuration Options

The Config struct provides several caching configuration options. The most commonly used option is TTL (Time To Live), which controls cache expiration.

TTL Configuration

Set the cache expiration time using the TTL field:

go
1getUserScoreFromDbWithCache := gofnext.CacheFn1Err(getUserScore, &gofnext.Config{
2    TTL: time.Hour,
3})

Evidence: examples/decorator-key_test.go:27-L29 demonstrates TTL configuration.

Short TTL Example

For testing or short-lived cache scenarios:

go
1getUserScoreFromDbWithCache := gofnext.CacheFn1Err(getUserScore, &gofnext.Config{
2    TTL: time.Millisecond * 10,
3})

Evidence: examples/decorator-ttl_test.go:19-L21 shows a 10-millisecond TTL configuration.

Error Handling Configuration

By default, errors are not cached. To cache errors along with successful results, use the ErrTTL configuration:

go
1getUserAndErrCached := gofnext.CacheFn1Err(getUserAndErr, &gofnext.Config{
2    ErrTTL: time.Hour,
3})

Evidence: examples/decorator-err_test.go:61-L63 demonstrates error caching configuration.

Error Handling Patterns

gofnext provides separate decorator functions for functions that return errors. Use CacheFn0Err, CacheFn1Err, etc., for functions with error return values.

Default Error Behavior

By default, errors are not cached, causing the function to be re-executed on each call when an error occurs:

go
1getUserAndErrCached := gofnext.CacheFn0Err(getUserWithErr, nil)

Evidence: examples/decorator-err_test.go:33 shows the default error handling behavior where errors are not cached.

Caching Errors

To cache errors (useful for preventing repeated failed operations), configure ErrTTL:

go
1getUserAndErrCached := gofnext.CacheFn1Err(getUserAndErr, &gofnext.Config{
2    ErrTTL: time.Hour,
3})

Evidence: examples/decorator-err_test.go:51-L63 demonstrates error caching with TTL.

Advanced Usage

Recursive Function Caching

gofnext supports caching for recursive functions, such as Fibonacci calculations:

go
1var fib func(int) int
2fib = func(x int) int {
3    if x <= 1 {
4        return x
5    } else {
6        return fib(x-1) + fib(x-2)
7    }
8}
9fib = gofnext.CacheFn1(fib)

Evidence: examples/decorator-fib_test.go:13-L23 demonstrates recursive function caching.

Complex Key Types

The library supports various key types including structs, maps, slices, and pointers.

Struct Keys

go
1type UserInfo struct {
2    Name string
3    Age  int
4    id   int
5}
6
7getUserScore := func(user UserInfo) (int, error) {
8    return 98 + user.id, nil
9}
10
11getUserScoreFromDbWithCache := gofnext.CacheFn1Err(getUserScore, &gofnext.Config{
12    TTL: time.Hour,
13})

Evidence: examples/decorator-key_test.go:12-L29 demonstrates struct key caching.

Map Keys

go
1type usermap = map[string]int
2
3getUserScore := func(user usermap) (int, error) {
4    return 98 + user["id"], nil
5}
6
7getUserScoreFromDbWithCache := gofnext.CacheFn1Err(getUserScore, &gofnext.Config{
8    TTL: time.Hour,
9})

Evidence: examples/decorator-key_test.go:72-L86 shows map key caching.

Pointer Keys

go
1getUserScore := func(user *UserInfo) (int, error) {
2    return 98 + user.id, nil
3}
4
5getUserScoreFromDbWithCache := gofnext.CacheFn1Err(getUserScore, &gofnext.Config{
6    TTL: time.Hour,
7})

Evidence: examples/decorator-key_test.go:170-L188 demonstrates pointer key caching.

Functions with More Than 3 Parameters

For functions with more than 3 parameters, wrap them in a struct:

go
1type Stu struct {
2    name   string
3    age    int
4    gender int
5    height int
6}
7
8getUserScoreOrigin := func(name string, age, gender, height int) int {
9    // implementation
10}
11
12fnWrap := func(arg Stu) int {
13    return getUserScoreOrigin(arg.name, arg.age, arg.gender, arg.height)
14}
15
16fnCachedInner := gofnext.CacheFn1(fnWrap)
17getUserScore := func(name string, age, gender, height int) int {
18    return fnCachedInner(Stu{name, age, gender, height})
19}

Evidence: examples/decorator_test.go:135-L166 demonstrates the wrapper pattern for functions with more than 3 parameters.

Verification

Running Tests

Verify the installation by running the example tests:

bash
1go test -v ./examples/...

This command executes all test cases in the examples directory, demonstrating various caching patterns.

Expected Test Output

Successful test execution should show all tests passing without errors. For example, the Fibonacci test verifies that caching reduces function calls:

go
1// TestFib verifies only 7 executions for fib(5) and fib(6) combined
2if excuteCount != 7 {
3    t.Errorf("Expected 7, but got %d", excuteCount)
4}

Evidence: examples/decorator-fib_test.go:27-L29 shows the expected execution count verification.

Parallel Execution Verification

The library handles concurrent access safely. Tests use parallel execution to verify thread safety:

go
1parallelCall(func() {
2    userinfo := getUserInfoCached(20)
3    fmt.Println(userinfo)
4}, 10)

Evidence: examples/decorator_test.go:35-L38 demonstrates parallel execution testing.

Troubleshooting

Issue 1: Cache Not Working as Expected

Symptom: Function executes multiple times despite caching.

Possible Causes:

• Different parameter values being passed
• TTL expired between calls
• Error returned (errors not cached by default)

Solution: Verify parameter consistency and check TTL configuration. For error cases, configure ErrTTL if error caching is desired:

go
1// Default: errors not cached
2getUserAndErrCached := gofnext.CacheFn0Err(getUserWithErr, nil)
3
4// With error caching
5getUserAndErrCached := gofnext.CacheFn1Err(getUserAndErr, &gofnext.Config{
6    ErrTTL: time.Hour,
7})

Evidence: examples/decorator-err_test.go:29-L47 demonstrates the difference between cached and non-cached error behavior.

Issue 2: TTL Timeout Not Working

Symptom: Cache entries persist longer than configured TTL.

Possible Cause: Insufficient wait time between test calls.

Solution: Ensure adequate sleep time exceeds the TTL:

go
1getUserScoreFromDbWithCache(1)
2time.Sleep(time.Millisecond * 11) // wait for ttl timeout (10ms TTL)
3getUserScoreFromDbWithCache(1)

Evidence: examples/decorator-ttl_test.go:24-L28 shows proper TTL timeout testing.

Issue 3: Unexported Fields in Struct Keys

Symptom: Caching behaves unexpectedly with structs containing unexported fields.

Solution: The library handles unexported fields in struct keys. Ensure consistent struct initialization:

go
1type UserInfo struct {
2    Name string
3    Age  int
4    id   int  // unexported field
5}
6
7getUserScoreFromDbWithCache(UserInfo{id: 1})

Evidence: examples/decorator-key_test.go:12-L16 demonstrates struct keys with unexported fields.

Issue 4: Recursive Function Stack Overflow

Symptom: Stack overflow when caching recursive functions.

Solution: Ensure the cache decorator is applied correctly to the recursive function variable:

go
1var fib func(int) int
2fib = func(x int) int {
3    if x <= 1 {
4        return x
5    } else {
6        return fib(x-1) + fib(x-2)
7    }
8}
9fib = gofnext.CacheFn1(fib)  // Apply after function definition

Evidence: examples/decorator-fib_test.go:13-L23 shows correct recursive function caching.

Next Steps

After completing the quick start, explore the following advanced topics:

1. Custom Cache Keys: Learn how to implement custom key generation logic for complex parameter types
2. Distributed Caching: Configure Redis backend for multi-instance deployments (requires confirmation - Redis configuration details not found in provided source files)
3. Serialization: Use the serial package for custom serialization needs as shown in examples/serial_test.go:8
4. Performance Tuning: Adjust TTL values and cache strategies based on workload patterns

For detailed API documentation and advanced configuration options, refer to the Usage Guide section.