Skip to content

API_SPECIFICATION.md

Latest commit

 

History

History
225 lines (158 loc) · 5.96 KB

API_SPECIFICATION.md

File metadata and controls

225 lines (158 loc) · 5.96 KB

performance - API Specification

Introduction

This document provides the complete API specification for the performance module.

Module Overview

The performance module provides utilities for optimizing application execution, including lazy loading, intelligent caching, and comprehensive performance monitoring.

Public API

Main Functions

function_name()

Description: Executes a specific operation with performance tracking.

Parameters:

  • param1 (type): Description
  • param2 (type, optional): Description

Returns: Return type and description

Example:

from codomyrmex.performance import function_name

result = function_name(param1="value")

Classes

ClassName

Description: Base class for performance-optimized components.

Methods:

  • method1(): Description
  • method2(param): Description

Constants

  • CONSTANT_NAME: Description

Exceptions

  • ModuleException: Description

Related Documentation

Functions

Function: lazy_import(module_name: str, **kwargs) -> LazyLoader

  • Description: Creates a lazy loader for importing modules on-demand to improve startup performance.
  • Parameters:
    • module_name: Name of the module to lazy load.
    • **kwargs: Additional configuration options.
  • Return Value: LazyLoader object that imports the module when first accessed.
  • Errors: Raises ImportError if the module cannot be found when accessed.

Function: cached_function(ttl_seconds: int = 300, max_size: int = 128, **kwargs) -> Callable

  • Description: Decorator that adds caching to functions to improve performance for expensive operations.
  • Parameters:
    • ttl_seconds: Time-to-live for cached results (default: 300 seconds).
    • max_size: Maximum number of cached results (default: 128).
    • **kwargs: Additional cache configuration options.
  • Return Value: Decorated function with caching capability.
  • Errors: Raises CacheError for cache configuration issues.

Classes

CacheManager

Description: Manages multiple cache instances with intelligent invalidation and memory management.

Methods

__init__(default_ttl: int = 300, max_memory_mb: int = 100, **kwargs)

  • Initialize cache manager with default settings.
  • Parameters: default_ttl, max_memory_mb, cache configuration options.
  • Errors: Raises CacheError for invalid configuration.

get_cache(name: str) -> Cache

  • Retrieve or create a named cache instance.
  • Parameters: name, cache identifier.
  • Return Value: Cache instance for the given name.

clear_cache(name: str = None)

  • Clear specific cache or all caches.
  • Parameters: name, optional cache name (clears all if None).

get_stats() -> Dict

  • Get cache performance statistics.
  • Return Value: Dictionary with hit rates, memory usage, and performance metrics.

LazyLoader

Description: Provides on-demand loading of modules and resources to improve application startup time.

Methods

__init__(loader: Callable, **kwargs)

  • Initialize lazy loader with loading function.
  • Parameters: loader, function that performs the actual loading.

load() -> Any

  • Perform the actual loading operation.
  • Return Value: Loaded resource or module.

is_loaded() -> bool

  • Check if the resource has been loaded.
  • Return Value: True if loaded, False otherwise.

PerformanceMonitor (Optional)

Description: Monitors application performance metrics (requires psutil).

Methods

start_monitoring(interval_seconds: float = 1.0)

  • Start performance monitoring with specified interval.
  • Parameters: interval_seconds, monitoring frequency.

stop_monitoring()

  • Stop performance monitoring.

get_metrics() -> Dict

  • Get current performance metrics.
  • Return Value: Dictionary with CPU, memory, disk, and network metrics.

get_report() -> str

  • Generate performance report.
  • Return Value: Formatted performance report string.

Data Structures

CacheConfig

Configuration for cache instances:

{
    "ttl_seconds": <int>,
    "max_size": <int>,
    "eviction_policy": "lru|lfu|random",
    "compression": <bool>,
    "persistent": <bool>
}

PerformanceMetrics

Performance monitoring data:

{
    "timestamp": <datetime>,
    "cpu_percent": <float>,
    "memory_percent": <float>,
    "memory_mb": <float>,
    "disk_read_mb": <float>,
    "disk_write_mb": <float>,
    "network_rx_mb": <float>,
    "network_tx_mb": <float>
}

Integration Examples

Lazy Loading for Heavy Imports

from codomyrmex.performance import lazy_import

# Lazy load heavy ML libraries
torch = lazy_import("torch")
transformers = lazy_import("transformers")

# Libraries are only imported when first accessed
model = torch.load("model.pth")  # Imports torch here

Function Caching

from codomyrmex.performance import cached_function

@cached_function(ttl_seconds=600, max_size=50)
def expensive_api_call(user_id: str) -> Dict:
    # Expensive database or API operation
    return get_user_data(user_id)

# First call performs operation and caches result
data1 = expensive_api_call("user123")

# Subsequent calls return cached result
data2 = expensive_api_call("user123")  # Returns cached data

Performance Monitoring

from codomyrmex.performance import PerformanceMonitor

monitor = PerformanceMonitor()
monitor.start_monitoring(interval_seconds=5.0)

# Run performance-critical code
perform_expensive_operation()

# Get performance report
report = monitor.get_report()
print(report)

monitor.stop_monitoring()

Navigation Links