# Understanding the Cache Package in CasaOS: In-Memory Storage for Performance

> Discover how the CasaOS cache package leverages in-memory storage to boost performance by reducing disk I/O and caching essential data like CPU thermal zones and version strings.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: internals
- Published: 2026-06-28

---

**The `pkg/cache` package provides a thread-safe, in-process key-value store that eliminates redundant disk I/O and system calls by caching frequently accessed data such as CPU thermal zones and version strings.**

The CasaOS home server operating system relies on the `pkg/cache` package to minimize expensive recomputation and external requests. This lightweight wrapper around `github.com/patrickmn/go-cache` creates a centralized, in-memory storage mechanism accessible throughout the service layer. By default, cached entries expire after five minutes with automatic cleanup occurring every minute.

## How the Cache Package Works in CasaOS

### Cache Initialization and Configuration

In [`pkg/cache/cache.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/cache/cache.go), the `Init()` function instantiates a `go-cache` instance with a **5-minute default expiration** and a **1-minute cleanup interval**. This configuration strikes a balance between data freshness and memory efficiency for a home server environment.

### Global Access Pattern

The cache becomes globally available during application startup. In [`main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go), the initialization call `service.Cache = cache.Init()` assigns the instance to the exported `Cache` variable declared in [`service/service.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/service.go). This pattern allows any service component to import the service package and interact with the cache without passing references through multiple layers.

## Key Use Cases in the CasaOS Codebase

### Caching CPU Thermal Zone Paths

Determining the Linux sysfs path for CPU temperature requires scanning system directories, an operation performed in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go). The `GetCPUThermalZone` function stores the discovered path under the key `cpu_thermal_zone` using `service.Cache.SetDefault()`, preventing repeated filesystem traversal on subsequent calls.

### Storing System Version Strings

The `casa_version` key caches the system-wide version string to support health checks and UI components. When the system updates, the `UpdateSystemVersion` function in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go) (lines 73-76) explicitly calls `service.Cache.Delete("casa_version")` to invalidate stale version data.

### General Service-Level Caching

Various services throughout `service/*.go` utilize `Cache.Set`, `Cache.Get`, and `Cache.Delete` for transient data that does not require persistent disk storage, such as temporary user settings or intermediate computation results.

## Implementation Details and Code Examples

The following patterns demonstrate how to interact with the CasaOS cache layer.

Initialize the cache during application startup:

```go
import "github.com/IceWhaleTech/CasaOS/pkg/cache"

func init() {
    // Global cache used by the service layer
    service.Cache = cache.Init()
}

```

Store values with default expiration:

```go
func cacheCPUPath(path string) {
    const key = "cpu_thermal_zone"
    // Uses the 5-minute expiration defined in cache.Init()
    service.Cache.SetDefault(key, path)
}

```

Retrieve cached values safely:

```go
func getCachedCPUPath() (string, bool) {
    const key = "cpu_thermal_zone"
    if v, ok := service.Cache.Get(key); ok {
        return v.(string), true
    }
    return "", false
}

```

Delete entries when data becomes stale:

```go
func clearVersionCache() {
    const key = "casa_version"
    service.Cache.Delete(key)
}

```

## Summary

- The `pkg/cache` package wraps `github.com/patrickmn/go-cache` to provide a centralized in-memory store with 5-minute expiration and 1-minute cleanup intervals.
- Initialization occurs in [`main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go) via `service.Cache = cache.Init()`, making the cache globally accessible through the service package.
- Critical system data like CPU thermal zone paths and version strings are cached in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go) to avoid redundant filesystem operations.
- The thread-safe implementation supports concurrent access across multiple services without additional synchronization logic.

## Frequently Asked Questions

### What is the default expiration time for cached items in CasaOS?

The default expiration is **5 minutes**, configured in the `Init()` function within [`pkg/cache/cache.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/cache/cache.go). The underlying library automatically removes expired entries during a cleanup interval of **1 minute**.

### How does CasaOS handle cache invalidation when system data changes?

Explicit invalidation occurs through the `Delete` method. For example, [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go) calls `service.Cache.Delete("casa_version")` inside `UpdateSystemVersion` to ensure the version string is refreshed immediately after a system update.

### Is the CasaOS cache package thread-safe for concurrent access?

Yes, the cache package is thread-safe. It wraps `go-cache`, which implements internal locking mechanisms. Multiple services can safely call `Get`, `Set`, and `Delete` operations concurrently without additional synchronization.

### Where is the cache instance stored and accessed in the CasaOS architecture?

The singleton instance is stored in the global `service.Cache` variable declared in [`service/service.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/service.go). This variable is initialized in [`main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main.go) and imported by service components such as [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go) to store and retrieve transient data.