Skip to main content

cache.go - Overview

  1. Overview This file defines the interface for a generic cache, including methods for connecting, storing, retrieving, and managing cached data. It also defines related types and constants for cacheable entities and retrieval statuses.

  2. Detailed Documentation

CacheableEntity​

  • Purpose: Interface for entities that can be stored in the cache. It requires implementations for binary marshaling and unmarshaling.
  • Methods:
    • MarshalBinary() ([]byte, error): Marshals the entity into a binary representation.
    • UnmarshalBinary(data []byte) error: Unmarshals the entity from a binary representation.

WrapCacheableEntityErrors​

  • Purpose: Returns an error formatted with the caller and type information if the provided reflect.Type rt represents a nil pointer or a non-pointer.
  • Parameters:
    • rt reflect.Type: The type to check.
    • caller string: The name of the calling function.
  • Returns: error: An error if rt is invalid; otherwise, returns nil.

RetrieveStatus​

  • Purpose: Represents the status of a cache retrieval operation.
  • Type: int
  • Constants:
    • RetrieveStatusHit: Indicates a successful retrieval from the cache.
    • RetrieveStatusPartialHit: Indicates a partial retrieval from the cache.
    • RetrieveStatusRangeMiss: Indicates a miss due to a range request not being satisfied.
    • RetrieveStatusKeyMiss: Indicates a cache miss.
    • RetrieveStatusRevalidated: Indicates that the cache entry was revalidated.
    • RetrieveStatusError: Indicates an error during retrieval.

RetrieveStatus.String​

  • Purpose: Returns a string representation of the RetrieveStatus.
  • Parameters:
    • s RetrieveStatus: The status to convert to a string.
  • Returns: string: A string representation of the status.

Cache​

  • Purpose: Interface for a generic cache.
  • Methods:
    • Connect(ctx context.Context) error: Establishes a connection to the cache.
      • Parameters:
        • ctx context.Context: The context for the operation.
      • Returns: error: An error if the connection fails.
    • Store(ctx context.Context, cacheKey string, data CacheableEntity, ttl time.Duration) error: Stores data in the cache.
      • Parameters:
        • ctx context.Context: The context for the operation.
        • cacheKey string: The key to use for storing the data.
        • data CacheableEntity: The data to store.
        • ttl time.Duration: The time-to-live for the data.
      • Returns: error: An error if the store operation fails.
    • Retrieve(ctx context.Context, cacheKey string, dest CacheableEntity, allowExpired bool) (RetrieveStatus, error): Retrieves data from the cache.
      • Parameters:
        • ctx context.Context: The context for the operation.
        • cacheKey string: The key to use for retrieving the data.
        • dest CacheableEntity: A pointer to the destination where the retrieved data will be stored.
        • allowExpired bool: Indicates whether to allow retrieving expired data.
      • Returns: (RetrieveStatus, error): The status of the retrieval and an error if the retrieval fails.
    • SetTTL(ctx context.Context, cacheKey string, ttl time.Duration): Sets the TTL for a cache entry.
      • Parameters:
        • ctx context.Context: The context for the operation.
        • cacheKey string: The key of the cache entry.
        • ttl time.Duration: The new TTL.
    • Remove(ctx context.Context, cacheKey string): Removes data from the cache.
      • Parameters:
        • ctx context.Context: The context for the operation.
        • cacheKey string: The key of the data to remove.
    • BulkRemove(ctx context.Context, cacheKeys []string): Removes multiple entries from the cache.
      • Parameters:
        • ctx context.Context: The context for the operation.
        • cacheKeys []string: A slice of keys to remove.
    • Close(ctx context.Context) error: Closes the connection to the cache.
      • Parameters:
        • ctx context.Context: The context for the operation.
      • Returns: error: An error if closing the connection fails.

  1. Code Examples N/A

  2. Clarity and Accuracy The documentation is based solely on the code provided.

  3. Markdown & MDX Perfection All markdown requirements have been met.

  4. Edge Cases To Avoid Breaking MDX All edge cases have been avoided.

  5. Getting Started Relevance Include in Getting Started: YES