shared-tensor 0.2.8__tar.gz → 0.2.10__tar.gz

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shared-tensor
-Version: 0.2.8
+Version: 0.2.10
 Summary: Native PyTorch CUDA IPC over Unix Domain Socket for same-host process separation
 Author-email: Athena Team <contact@world-sim-dev.org>
 Maintainer-email: Athena Team <contact@world-sim-dev.org>
@@ -21,15 +21,16 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
-Requires-Python: <3.14,>=3.9
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cloudpickle>=3.0.0
 Requires-Dist: numpy<2
-Requires-Dist: torch<2.8,>=2.1
+Requires-Dist: torch>=2.1
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-cov>=2.0; extra == "dev"
@@ -64,7 +65,7 @@ Supported:
 - explicit endpoint registration
 - sync `call` and task-backed `submit`
 - managed object handles with explicit release
-- server-side caching, `cache_format_key`, and singleflight
+- server-side caching, `cache_format_key`, singleflight, and explicit cache invalidation
 - manual two-process deployment as the primary production path
 - zero-branch auto mode gated by `SHARED_TENSOR_ENABLED=1`
 
@@ -107,6 +108,8 @@ Production should prefer two explicitly started processes: one server process th
 
 See [examples/model_service.py](./examples/model_service.py) for endpoint definitions.
 
+The server-oriented example modules construct providers with explicit `execution_mode="server"` so importing the module already reflects the intended deployment role.
+
 Server process:
 
 ```python
@@ -147,10 +150,32 @@ executes endpoint functions         reopens CUDA objects via torch IPC
 manages cache and refcounts         releases managed handles explicitly
 ```
 
+## Lifetime And Failure Contract
+
+`shared_tensor` follows native PyTorch CUDA IPC semantics. It does not virtualize or harden producer lifetime.
+
+Core assumption:
+- the server process that owns the original CUDA allocation must stay alive while clients are still using reopened CUDA tensors or modules
+- handle health checks can detect some stale-object conditions, but they do not remove the producer-liveness requirement
+
+If the server exits, crashes, or is killed before the client is done with the shared CUDA object, behavior is no longer guaranteed by this library. Depending on PyTorch and CUDA runtime state, the client may see CUDA runtime errors, invalid resource handle failures, broken module execution, or process-level instability.
+
+So the production contract is:
+- client-side handles are only valid while the producer process remains alive
+- `handle.release()` is explicit lifecycle cleanup, not durability
+- this library does not promise survivability across producer death
+
+Treat producer liveness as a hard requirement, not a soft optimization.
+
 ## Example: Same Code, Two Processes
 
 See [examples/zero_branch_env.py](./examples/zero_branch_env.py). This is a convenience mode for environments that want one file and environment-controlled behavior.
 
+Resolution rule:
+- `SHARED_TENSOR_ENABLED` unset or false: provider stays local
+- `SHARED_TENSOR_ENABLED=1` and `SHARED_TENSOR_ROLE=server`: provider resolves to server and auto-starts the thread-backed local server
+- `SHARED_TENSOR_ENABLED=1` and role unset or `client`: provider resolves to client
+
 ```bash
 SHARED_TENSOR_ENABLED=1 SHARED_TENSOR_ROLE=server python demo.py
 SHARED_TENSOR_ENABLED=1 python demo.py
@@ -168,6 +193,27 @@ shared function runs locally        shared function becomes RPC call
 CUDA object stays on same GPU       CUDA object is reopened via torch IPC
 ```
 
+## Example: Task Submission And Wait
+
+See [examples/async_service.py](./examples/async_service.py).
+
+```python
+from shared_tensor import AsyncSharedTensorClient, SharedTensorProvider
+
+provider = SharedTensorProvider(execution_mode="server")
+
+@provider.share(execution="task")
+def build_delayed_model(delay: float = 0.1):
+    ...
+
+client = AsyncSharedTensorClient()
+task_id = client.submit("build_delayed_model", delay=0.1)
+model = client.wait_for_task(task_id, timeout=30)
+```
+
+Use `SharedTensorProvider(execution="task")` for task-backed endpoints.
+Use `AsyncSharedTensorClient` when you want a task-oriented waiting interface.
+
 ## Example: Reusable Model Registry
 
 See [examples/model_service.py](./examples/model_service.py).
@@ -278,11 +324,47 @@ handle.release()
 ```
 
 Use managed mode for cached models or other reusable long-lived CUDA objects.
+Managed object introspection now includes `created_at` and `last_accessed_at` timestamps through `get_object_info()`.
+
+## Cache Invalidation
+
+The library now exposes explicit cache invalidation instead of forcing process restarts when a cached object becomes stale.
+
+```python
+provider.invalidate_call_cache("load_model", hidden_size=4096)
+provider.invalidate_endpoint_cache("load_model")
+```
+
+Client-side equivalents are also available:
+
+```python
+client.invalidate_call_cache("load_model", hidden_size=4096)
+client.invalidate_endpoint_cache("load_model")
+```
+
+Use call-level invalidation when you want to evict one cache key.
+Use endpoint-level invalidation when you want to drop all cached variants for the endpoint.
+Invalidation removes cache lookup entries; it does not guarantee that already-issued client handles remain valid after producer death.
+
+
+## Handle Health Checks
+
+Managed handles now carry the producer `server_id` and support lightweight liveness probes:
+
+```python
+handle = client.call("load_model", hidden_size=4096)
+info = handle.get_object_info()
+client.ensure_handle_live(handle)
+```
+
+If the producer no longer owns the object, `client.ensure_handle_live(handle)` raises `SharedTensorStaleHandleError`.
+This is still advisory, not a durability guarantee: it helps detect stale handles earlier, but it cannot make producer death safe.
 
 ## Runtime Introspection
 
-`client.get_server_info()` now returns readiness and process metadata in addition to endpoint and capability data.
+`client.get_server_info()` now returns readiness, stable `server_id`, cache/task counters, and process metadata in addition to endpoint and capability data.
 In client mode, `provider.get_runtime_info()` wraps that into a provider-oriented view.
+`AsyncSharedTensorClient` exposes the same runtime, cache invalidation, release, and handle-health helper methods as `SharedTensorClient`; the async surface is task-oriented, not capability-reduced.
 
 ```python
 info = provider.get_runtime_info()

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/README.md

@@ -12,7 +12,7 @@ Supported:
 - explicit endpoint registration
 - sync `call` and task-backed `submit`
 - managed object handles with explicit release
-- server-side caching, `cache_format_key`, and singleflight
+- server-side caching, `cache_format_key`, singleflight, and explicit cache invalidation
 - manual two-process deployment as the primary production path
 - zero-branch auto mode gated by `SHARED_TENSOR_ENABLED=1`
 
@@ -55,6 +55,8 @@ Production should prefer two explicitly started processes: one server process th
 
 See [examples/model_service.py](./examples/model_service.py) for endpoint definitions.
 
+The server-oriented example modules construct providers with explicit `execution_mode="server"` so importing the module already reflects the intended deployment role.
+
 Server process:
 
 ```python
@@ -95,10 +97,32 @@ executes endpoint functions         reopens CUDA objects via torch IPC
 manages cache and refcounts         releases managed handles explicitly
 ```
 
+## Lifetime And Failure Contract
+
+`shared_tensor` follows native PyTorch CUDA IPC semantics. It does not virtualize or harden producer lifetime.
+
+Core assumption:
+- the server process that owns the original CUDA allocation must stay alive while clients are still using reopened CUDA tensors or modules
+- handle health checks can detect some stale-object conditions, but they do not remove the producer-liveness requirement
+
+If the server exits, crashes, or is killed before the client is done with the shared CUDA object, behavior is no longer guaranteed by this library. Depending on PyTorch and CUDA runtime state, the client may see CUDA runtime errors, invalid resource handle failures, broken module execution, or process-level instability.
+
+So the production contract is:
+- client-side handles are only valid while the producer process remains alive
+- `handle.release()` is explicit lifecycle cleanup, not durability
+- this library does not promise survivability across producer death
+
+Treat producer liveness as a hard requirement, not a soft optimization.
+
 ## Example: Same Code, Two Processes
 
 See [examples/zero_branch_env.py](./examples/zero_branch_env.py). This is a convenience mode for environments that want one file and environment-controlled behavior.
 
+Resolution rule:
+- `SHARED_TENSOR_ENABLED` unset or false: provider stays local
+- `SHARED_TENSOR_ENABLED=1` and `SHARED_TENSOR_ROLE=server`: provider resolves to server and auto-starts the thread-backed local server
+- `SHARED_TENSOR_ENABLED=1` and role unset or `client`: provider resolves to client
+
 ```bash
 SHARED_TENSOR_ENABLED=1 SHARED_TENSOR_ROLE=server python demo.py
 SHARED_TENSOR_ENABLED=1 python demo.py
@@ -116,6 +140,27 @@ shared function runs locally        shared function becomes RPC call
 CUDA object stays on same GPU       CUDA object is reopened via torch IPC
 ```
 
+## Example: Task Submission And Wait
+
+See [examples/async_service.py](./examples/async_service.py).
+
+```python
+from shared_tensor import AsyncSharedTensorClient, SharedTensorProvider
+
+provider = SharedTensorProvider(execution_mode="server")
+
+@provider.share(execution="task")
+def build_delayed_model(delay: float = 0.1):
+    ...
+
+client = AsyncSharedTensorClient()
+task_id = client.submit("build_delayed_model", delay=0.1)
+model = client.wait_for_task(task_id, timeout=30)
+```
+
+Use `SharedTensorProvider(execution="task")` for task-backed endpoints.
+Use `AsyncSharedTensorClient` when you want a task-oriented waiting interface.
+
 ## Example: Reusable Model Registry
 
 See [examples/model_service.py](./examples/model_service.py).
@@ -226,11 +271,47 @@ handle.release()
 ```
 
 Use managed mode for cached models or other reusable long-lived CUDA objects.
+Managed object introspection now includes `created_at` and `last_accessed_at` timestamps through `get_object_info()`.
+
+## Cache Invalidation
+
+The library now exposes explicit cache invalidation instead of forcing process restarts when a cached object becomes stale.
+
+```python
+provider.invalidate_call_cache("load_model", hidden_size=4096)
+provider.invalidate_endpoint_cache("load_model")
+```
+
+Client-side equivalents are also available:
+
+```python
+client.invalidate_call_cache("load_model", hidden_size=4096)
+client.invalidate_endpoint_cache("load_model")
+```
+
+Use call-level invalidation when you want to evict one cache key.
+Use endpoint-level invalidation when you want to drop all cached variants for the endpoint.
+Invalidation removes cache lookup entries; it does not guarantee that already-issued client handles remain valid after producer death.
+
+
+## Handle Health Checks
+
+Managed handles now carry the producer `server_id` and support lightweight liveness probes:
+
+```python
+handle = client.call("load_model", hidden_size=4096)
+info = handle.get_object_info()
+client.ensure_handle_live(handle)
+```
+
+If the producer no longer owns the object, `client.ensure_handle_live(handle)` raises `SharedTensorStaleHandleError`.
+This is still advisory, not a durability guarantee: it helps detect stale handles earlier, but it cannot make producer death safe.
 
 ## Runtime Introspection
 
-`client.get_server_info()` now returns readiness and process metadata in addition to endpoint and capability data.
+`client.get_server_info()` now returns readiness, stable `server_id`, cache/task counters, and process metadata in addition to endpoint and capability data.
 In client mode, `provider.get_runtime_info()` wraps that into a provider-oriented view.
+`AsyncSharedTensorClient` exposes the same runtime, cache invalidation, release, and handle-health helper methods as `SharedTensorClient`; the async surface is task-oriented, not capability-reduced.
 
 ```python
 info = provider.get_runtime_info()

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shared-tensor"
-version = "0.2.8"
+version = "0.2.10"
 description = "Native PyTorch CUDA IPC over Unix Domain Socket for same-host process separation"
 readme = "README.md"
 license = "Apache-2.0"
@@ -38,15 +38,16 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: System :: Distributed Computing",
 ]
-requires-python = ">=3.9,<3.14"
+requires-python = ">=3.9"
 dependencies = [
     "cloudpickle>=3.0.0",
     "numpy<2",
-    "torch>=2.1,<2.8",
+    "torch>=2.1",
 ]
 
 [project.optional-dependencies]

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor/__init__.py

@@ -1,22 +1,22 @@
 """shared_tensor: same-host same-GPU PyTorch CUDA IPC over local UDS RPC."""
 
 from shared_tensor.async_client import AsyncSharedTensorClient
-from shared_tensor.async_provider import AsyncSharedTensorProvider
 from shared_tensor.async_task import TaskInfo, TaskStatus
 from shared_tensor.client import SharedTensorClient
+from shared_tensor.errors import SharedTensorStaleHandleError
 from shared_tensor.managed_object import SharedObjectHandle
 from shared_tensor.provider import SharedTensorProvider
 from shared_tensor.server import SharedTensorServer
 
 __all__ = [
     "AsyncSharedTensorClient",
-    "AsyncSharedTensorProvider",
     "SharedTensorClient",
     "SharedObjectHandle",
+    "SharedTensorStaleHandleError",
     "SharedTensorProvider",
     "SharedTensorServer",
     "TaskInfo",
     "TaskStatus",
 ]
 
-__version__ = "0.2.8"
+__version__ = "0.2.10"

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor/async_client.py

@@ -10,6 +10,7 @@ from typing import Any, cast
 from shared_tensor.async_task import TaskInfo, TaskStatus
 from shared_tensor.client import SharedTensorClient
 from shared_tensor.errors import SharedTensorRemoteError, SharedTensorTaskError
+from shared_tensor.managed_object import SharedObjectHandle
 
 
 logger = logging.getLogger(__name__)
@@ -51,6 +52,38 @@ class AsyncSharedTensorClient:
     def get_task_result(self, task_id: str) -> Any:
         return self.result(task_id)
 
+    def ping(self) -> bool:
+        return self._client.ping()
+
+    def get_server_info(self) -> dict[str, Any]:
+        return self._client.get_server_info()
+
+    def list_endpoints(self) -> dict[str, Any]:
+        return self._client.list_endpoints()
+
+    def release(self, object_id: str) -> bool:
+        return self._client.release(object_id)
+
+    def release_many(self, object_ids: list[str]) -> dict[str, bool]:
+        return self._client.release_many(object_ids)
+
+    def get_object_info(self, object_id: str) -> dict[str, Any] | None:
+        return self._client.get_object_info(object_id)
+
+    def ensure_handle_live(
+        self,
+        handle: SharedObjectHandle[Any],
+        *,
+        refresh: bool = True,
+    ) -> dict[str, Any]:
+        return self._client.ensure_handle_live(handle, refresh=refresh)
+
+    def invalidate_call_cache(self, endpoint: str, *args: Any, **kwargs: Any) -> bool:
+        return self._client.invalidate_call_cache(endpoint, *args, **kwargs)
+
+    def invalidate_endpoint_cache(self, endpoint: str) -> int:
+        return self._client.invalidate_endpoint_cache(endpoint)
+
     def wait(
         self,
         task_id: str,

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor/client.py

@@ -7,6 +7,7 @@ import socket
 from dataclasses import dataclass
 from typing import Any, cast
 
+from shared_tensor.async_task import TaskStatus
 from shared_tensor.errors import (
     SharedTensorCapabilityError,
     SharedTensorClientError,
@@ -16,12 +17,12 @@ from shared_tensor.errors import (
     SharedTensorProtocolError,
     SharedTensorRemoteError,
     SharedTensorSerializationError,
+    SharedTensorStaleHandleError,
     SharedTensorTaskError,
 )
 from shared_tensor.managed_object import ReleaseHandle, SharedObjectHandle
 from shared_tensor.runtime import get_local_server
 from shared_tensor.transport import recv_message, send_message
-from shared_tensor.async_task import TaskStatus
 from shared_tensor.utils import (
     deserialize_payload,
     resolve_runtime_socket_path,
@@ -29,7 +30,6 @@ from shared_tensor.utils import (
     validate_payload_for_transport,
 )
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -41,6 +41,9 @@ class _ClientReleaser(ReleaseHandle):
     def release(self) -> bool:
         return self.client.release(self.object_id)
 
+    def get_object_info(self) -> dict[str, Any] | None:
+        return self.client.get_object_info(self.object_id)
+
 
 class SharedTensorClient:
     """UDS client for endpoint-oriented local RPC execution."""
@@ -76,6 +79,8 @@ class SharedTensorClient:
             code = 5
         elif isinstance(exc, SharedTensorConfigurationError):
             code = 6
+        elif isinstance(exc, SharedTensorStaleHandleError):
+            code = 8
         else:
             code = 7
         return SharedTensorRemoteError(
@@ -105,6 +110,7 @@ class SharedTensorClient:
             object_id=cast(str, object_id),
             value=value,
             _releaser=_ClientReleaser(client=self, object_id=cast(str, object_id)),
+            server_id=self._infer_server_id(),
         )
 
     def _send_request(self, request: dict[str, Any]) -> Any:
@@ -158,6 +164,15 @@ class SharedTensorClient:
     def _request(self, method: str, params: dict[str, Any] | None = None) -> Any:
         return self._send_request({"method": method, "params": params or {}})
 
+    def _infer_server_id(self) -> str | None:
+        local_server = self._local_server()
+        if local_server is not None:
+            return cast(str | None, getattr(local_server, "server_id", None))
+        try:
+            return cast(str | None, self.get_server_info().get("server_id"))
+        except (SharedTensorClientError, SharedTensorRemoteError, SharedTensorProtocolError):
+            return None
+
     def call(self, endpoint: str, *args: Any, **kwargs: Any) -> Any:
         if self.verbose_debug:
             logger.debug("Client calling endpoint", extra={"endpoint": endpoint})
@@ -245,6 +260,25 @@ class SharedTensorClient:
         result = self._request("get_object_info", {"object_id": object_id})
         return cast(dict[str, Any] | None, result.get("object"))
 
+    def ensure_handle_live(self, handle: SharedObjectHandle[Any], *, refresh: bool = True) -> dict[str, Any]:
+        info = handle.get_object_info(refresh=refresh)
+        if info is None:
+            raise SharedTensorStaleHandleError(
+                f"Managed object '{handle.object_id}' is no longer registered on the producer",
+                object_id=handle.object_id,
+                server_id=handle.server_id,
+                reason="object_missing",
+            )
+        observed_server_id = cast(str | None, info.get("server_id"))
+        if handle.server_id is not None and observed_server_id is not None and observed_server_id != handle.server_id:
+            raise SharedTensorStaleHandleError(
+                f"Managed object '{handle.object_id}' belongs to server '{handle.server_id}' but producer now reports '{observed_server_id}'",
+                object_id=handle.object_id,
+                server_id=handle.server_id,
+                reason="server_mismatch",
+            )
+        return info
+
     def ping(self) -> bool:
         if self._local_server() is not None:
             return True
@@ -260,6 +294,31 @@ class SharedTensorClient:
             return self._run_local(lambda: cast(dict[str, Any], local_server._get_server_info()))
         return cast(dict[str, Any], self._request("get_server_info"))
 
+    def invalidate_call_cache(self, endpoint: str, *args: Any, **kwargs: Any) -> bool:
+        local_server = self._local_server()
+        if local_server is not None:
+            return self._run_local(
+                lambda: bool(local_server.invalidate_call_cache(endpoint, args=tuple(args), kwargs=dict(kwargs)))
+            )
+        encoding, args_payload, kwargs_payload = serialize_call_payloads(tuple(args), dict(kwargs))
+        result = self._request(
+            "invalidate_call_cache",
+            {
+                "endpoint": endpoint,
+                "args_bytes": args_payload,
+                "kwargs_bytes": kwargs_payload,
+                "encoding": encoding,
+            },
+        )
+        return bool(result["invalidated"])
+
+    def invalidate_endpoint_cache(self, endpoint: str) -> int:
+        local_server = self._local_server()
+        if local_server is not None:
+            return self._run_local(lambda: int(local_server.invalidate_endpoint_cache(endpoint)))
+        result = self._request("invalidate_endpoint_cache", {"endpoint": endpoint})
+        return int(result["invalidated"])
+
     def list_endpoints(self) -> dict[str, Any]:
         local_server = self._local_server()
         if local_server is not None:
@@ -344,4 +403,5 @@ class SharedTensorClient:
             object_id=cast(str, object_id),
             value=value,
             _releaser=_ClientReleaser(client=self, object_id=cast(str, object_id)),
+            server_id=cast(str | None, result.get("server_id")),
         )

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor/errors.py

@@ -15,6 +15,7 @@ __all__ = [
     "SharedTensorClientError",
     "SharedTensorServerError",
     "SharedTensorProviderError",
+    "SharedTensorStaleHandleError",
 ]
 
 
@@ -69,3 +70,20 @@ class SharedTensorServerError(SharedTensorError):
 
 class SharedTensorProviderError(SharedTensorError):
     """Raised for provider registration or invocation problems."""
+
+
+class SharedTensorStaleHandleError(SharedTensorError):
+    """Raised when a managed handle can no longer be trusted."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        object_id: str | None = None,
+        server_id: str | None = None,
+        reason: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.object_id = object_id
+        self.server_id = server_id
+        self.reason = reason

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor/managed_object.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+import time
 import uuid
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from threading import RLock
 from typing import Any, Generic, TypeVar
 
@@ -17,6 +18,8 @@ class ManagedObjectEntry:
     endpoint: str
     cache_key: str | None
     refcount: int = 1
+    created_at: float = 0.0
+    last_accessed_at: float = 0.0
 
 
 @dataclass(slots=True)
@@ -42,15 +45,19 @@ class ManagedObjectRegistry:
             if entry is None:
                 self._cache_index.pop(cache_key, None)
                 return None
+            entry.last_accessed_at = time.time()
             return entry
 
     def register(self, *, endpoint: str, value: Any, cache_key: str | None) -> ManagedObjectEntry:
         with self._lock:
+            now = time.time()
             entry = ManagedObjectEntry(
                 object_id=uuid.uuid4().hex,
                 value=value,
                 endpoint=endpoint,
                 cache_key=cache_key,
+                created_at=now,
+                last_accessed_at=now,
             )
             self._entries[entry.object_id] = entry
             if cache_key is not None:
@@ -67,6 +74,7 @@ class ManagedObjectRegistry:
             if entry is None:
                 return None
             entry.refcount += 1
+            entry.last_accessed_at = time.time()
             return entry
 
     def release(self, object_id: str) -> ManagedReleaseResult:
@@ -100,6 +108,31 @@ class ManagedObjectRegistry:
                 "endpoint": entry.endpoint,
                 "cache_key": entry.cache_key,
                 "refcount": entry.refcount,
+                "created_at": entry.created_at,
+                "last_accessed_at": entry.last_accessed_at,
+            }
+
+    def invalidate_cache_key(self, cache_key: str) -> bool:
+        with self._lock:
+            object_id = self._cache_index.pop(cache_key, None)
+            return object_id is not None
+
+    def invalidate_endpoint(self, endpoint: str) -> int:
+        with self._lock:
+            keys = [
+                cache_key
+                for cache_key, object_id in self._cache_index.items()
+                if (entry := self._entries.get(object_id)) is not None and entry.endpoint == endpoint
+            ]
+            for cache_key in keys:
+                self._cache_index.pop(cache_key, None)
+            return len(keys)
+
+    def stats(self) -> dict[str, int]:
+        with self._lock:
+            return {
+                "objects": len(self._entries),
+                "cached_objects": len(self._cache_index),
             }
 
     def clear(self) -> None:
@@ -112,6 +145,9 @@ class ReleaseHandle:
     def release(self) -> bool:  # pragma: no cover - protocol surface only
         raise NotImplementedError
 
+    def get_object_info(self) -> dict[str, Any] | None:  # pragma: no cover - protocol surface only
+        raise NotImplementedError
+
 
 @dataclass(slots=True)
 class SharedObjectHandle(Generic[T]):
@@ -119,6 +155,8 @@ class SharedObjectHandle(Generic[T]):
     value: T
     _releaser: ReleaseHandle
     released: bool = False
+    server_id: str | None = None
+    _metadata_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
 
     def release(self) -> bool:
         if self.released:
@@ -126,8 +164,19 @@ class SharedObjectHandle(Generic[T]):
         released = self._releaser.release()
         if released:
             self.released = True
+            self._metadata_cache = None
         return released
 
+    def get_object_info(self, *, refresh: bool = False) -> dict[str, Any] | None:
+        if self.released:
+            return None
+        if self._metadata_cache is None or refresh:
+            self._metadata_cache = self._releaser.get_object_info()
+        return None if self._metadata_cache is None else dict(self._metadata_cache)
+
+    def is_stale(self) -> bool:
+        return self.get_object_info(refresh=True) is None
+
     def __enter__(self) -> SharedObjectHandle[T]:
         return self
 

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor/provider.py

@@ -112,6 +112,7 @@ class SharedTensorProvider:
         self._async_client: Any | None = None
         self._server: Any | None = None
         self._cache: dict[str, Any] = {}
+        self._cache_key_index: dict[str, str] = {}
         self._endpoints: dict[str, EndpointDefinition] = {}
         self._registered_functions = self._endpoints
         self._lock = RLock()
@@ -263,6 +264,35 @@ class SharedTensorProvider:
     def list_tasks(self, status: str | None = None) -> dict[str, Any]:
         return self._get_async_client().list_tasks(status=status)
 
+    def invalidate_call_cache(self, endpoint: str, *args: Any, **kwargs: Any) -> bool:
+        if self.execution_mode == "server":
+            if self._server is not None and hasattr(self._server, "invalidate_call_cache"):
+                return bool(self._server.invalidate_call_cache(endpoint, args=args, kwargs=kwargs))
+            return False
+        if self.execution_mode == "local":
+            definition = self.get_endpoint(endpoint)
+            cache_key = self._cache_key_for(endpoint, definition, args, kwargs)
+            with self._lock:
+                removed = self._cache.pop(cache_key, None)
+                self._cache_key_index.pop(cache_key, None)
+            return removed is not None
+        return self._get_client().invalidate_call_cache(endpoint, *args, **kwargs)
+
+    def invalidate_endpoint_cache(self, endpoint: str) -> int:
+        if self.execution_mode == "server":
+            if self._server is not None and hasattr(self._server, "invalidate_endpoint_cache"):
+                return int(self._server.invalidate_endpoint_cache(endpoint))
+            return 0
+        if self.execution_mode == "local":
+            self.get_endpoint(endpoint)
+            with self._lock:
+                keys = [cache_key for cache_key, cache_endpoint in self._cache_key_index.items() if cache_endpoint == endpoint]
+                for cache_key in keys:
+                    self._cache.pop(cache_key, None)
+                    self._cache_key_index.pop(cache_key, None)
+            return len(keys)
+        return self._get_client().invalidate_endpoint_cache(endpoint)
+
     def invoke_local(
         self,
         endpoint: str,
@@ -283,6 +313,7 @@ class SharedTensorProvider:
         result = definition.func(*args, **resolved_kwargs)
         with self._lock:
             self._cache[cache_key] = result
+            self._cache_key_index[cache_key] = endpoint
         return result
 
     def get_endpoint(self, endpoint: str) -> EndpointDefinition:
@@ -328,6 +359,8 @@ class SharedTensorProvider:
                 "device_index": self.device_index,
                 "server_socket_path": resolve_runtime_socket_path(self.base_path, self.device_index),
                 "server_running": bool(server is not None and getattr(server, "running", True)),
+                "endpoint_count": len(self._endpoints),
+                "cache_entries": len(self._cache),
             }
         server_info = self._get_client().get_server_info()
         return {
@@ -338,6 +371,7 @@ class SharedTensorProvider:
             "server_socket_path": server_info.get("socket_path"),
             "server_running": bool(server_info.get("running")),
             "server_ready": bool(server_info.get("ready")),
+            "endpoint_count": len(self._endpoints),
             "server_info": server_info,
         }
 

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor/server.py

@@ -7,6 +7,7 @@ import os
 import socket
 import threading
 import time
+import uuid
 from concurrent.futures import Future
 from dataclasses import dataclass, field
 from typing import Any
@@ -18,6 +19,7 @@ from shared_tensor.errors import (
     SharedTensorProtocolError,
     SharedTensorProviderError,
     SharedTensorSerializationError,
+    SharedTensorStaleHandleError,
     SharedTensorTaskError,
 )
 from shared_tensor.managed_object import ManagedObjectRegistry
@@ -110,6 +112,7 @@ class SharedTensorServer:
         self.startup_timeout = startup_timeout
         self.listener: socket.socket | None = None
         self.server_process: Any | None = None
+        self.server_id = uuid.uuid4().hex
         self.server_thread: _ServerThreadState | None = None
         self._resolved_process_start_method: str | None = None
         self.running = False
@@ -117,9 +120,13 @@ class SharedTensorServer:
         self.stats = {
             "requests_processed": 0,
             "errors_encountered": 0,
+            "cache_hits": 0,
+            "cache_misses": 0,
+            "task_submissions": 0,
+            "cache_invalidations": 0,
         }
         self._task_manager: TaskManager | None = None
-        self._cache: dict[str, dict[str, Any]] = {}
+        self._cache: dict[str, str] = {}
         self._local_cache: dict[str, Any] = {}
         self._managed_objects = ManagedObjectRegistry()
         self._inflight: dict[str, _InFlightCall] = {}
@@ -182,6 +189,10 @@ class SharedTensorServer:
             return self._handle_release_objects(params)
         if method == "get_object_info":
             return self._handle_get_object_info(params)
+        if method == "invalidate_call_cache":
+            return self._handle_invalidate_call_cache(params)
+        if method == "invalidate_endpoint_cache":
+            return self._handle_invalidate_endpoint_cache(params)
         raise SharedTensorProtocolError(f"Unknown RPC method '{method}'")
 
     def _handle_call(self, params: dict[str, Any]) -> dict[str, Any]:
@@ -224,6 +235,7 @@ class SharedTensorServer:
         args: tuple[Any, ...],
         kwargs: dict[str, Any],
     ) -> Any:
+        self.stats["task_submissions"] += 1
         return self._task_manager_instance().submit(
             endpoint,
             self._execute_endpoint_result,
@@ -243,9 +255,11 @@ class SharedTensorServer:
         if cache_key is not None:
             cached = self._lookup_cached_result_value(definition, cache_key)
             if cached is not None:
+                self.stats["cache_hits"] += 1
                 if self.verbose_debug:
                     logger.debug("Server cache hit", extra={"endpoint": endpoint, "cache_key": cache_key})
                 return cached
+            self.stats["cache_misses"] += 1
 
         inflight_key = cache_key if cache_key is not None and definition.singleflight else None
         if inflight_key is not None:
@@ -317,6 +331,7 @@ class SharedTensorServer:
         if cache_key is not None:
             with self._coordination_lock:
                 self._local_cache[cache_key] = value
+                self._cache[cache_key] = endpoint
         return _EndpointResult(value=value)
 
     def _materialize_managed_result(
@@ -337,6 +352,9 @@ class SharedTensorServer:
         if self.verbose_debug:
             logger.debug("Server created managed object", extra={"endpoint": endpoint, "cache_key": cache_key})
         entry = self._managed_objects.register(endpoint=endpoint, value=result, cache_key=cache_key)
+        if cache_key is not None:
+            with self._coordination_lock:
+                self._cache[cache_key] = endpoint
         return _EndpointResult(value=entry.value, object_id=entry.object_id)
 
     def _lookup_cached_result_value(
@@ -353,9 +371,9 @@ class SharedTensorServer:
             self._managed_objects.add_ref(cached.object_id)
             return _EndpointResult(value=cached.value, object_id=cached.object_id)
         with self._coordination_lock:
-            local_value = self._local_cache.get(cache_key)
-        if local_value is None:
-            return None
+            if cache_key not in self._local_cache:
+                return None
+            local_value = self._local_cache[cache_key]
         return _EndpointResult(value=local_value)
 
     def call_local_client(
@@ -413,22 +431,30 @@ class SharedTensorServer:
             if cache_key is not None:
                 cached = self._managed_objects.get_cached(cache_key)
                 if cached is not None:
+                    self.stats["cache_hits"] += 1
                     return cached.value
+                self.stats["cache_misses"] += 1
             value = definition.func(*args, **resolved_kwargs)
             if cache_key is not None:
                 existing = self._managed_objects.get_cached(cache_key)
                 if existing is not None:
+                    self.stats["cache_hits"] += 1
                     return existing.value
                 self._managed_objects.register(endpoint=endpoint, value=value, cache_key=cache_key)
+                with self._coordination_lock:
+                    self._cache[cache_key] = endpoint
             return value
         if cache_key is not None:
             with self._coordination_lock:
                 if cache_key in self._local_cache:
+                    self.stats["cache_hits"] += 1
                     return self._local_cache[cache_key]
+            self.stats["cache_misses"] += 1
         value = definition.func(*args, **resolved_kwargs)
         if cache_key is not None:
             with self._coordination_lock:
                 self._local_cache[cache_key] = value
+                self._cache[cache_key] = endpoint
         return value
 
     def _cache_key(
@@ -498,7 +524,21 @@ class SharedTensorServer:
 
     def _handle_get_object_info(self, params: dict[str, Any]) -> dict[str, Any]:
         object_id = self._require_object_id(params)
-        return {"object": self._managed_objects.info(object_id)}
+        info = self._managed_objects.info(object_id)
+        if info is None:
+            return {"object": None}
+        return {"object": {**info, "server_id": self.server_id}}
+
+    def _handle_invalidate_call_cache(self, params: dict[str, Any]) -> dict[str, Any]:
+        endpoint, args, kwargs = self._decode_call_params(params)
+        removed = self.invalidate_call_cache(endpoint, args=args, kwargs=kwargs)
+        return {"invalidated": removed}
+
+    def _handle_invalidate_endpoint_cache(self, params: dict[str, Any]) -> dict[str, Any]:
+        endpoint = params.get("endpoint")
+        if not isinstance(endpoint, str) or not endpoint:
+            raise SharedTensorProtocolError("Missing required parameter 'endpoint'")
+        return {"invalidated": self.invalidate_endpoint_cache(endpoint)}
 
     def _decode_call_params(self, params: dict[str, Any]) -> tuple[str, tuple[Any, ...], dict[str, Any]]:
         endpoint = params.get("endpoint")
@@ -523,14 +563,34 @@ class SharedTensorServer:
         validate_call_payload_for_transport(kwargs, allow_dict_keys=True)
         return endpoint, args, kwargs
 
-    def _encode_result(self, value: Any, *, object_id: str | None = None) -> dict[str, Any]:
+    def _encode_result(
+        self,
+        value: Any,
+        *,
+        object_id: str | None = None,
+        server_id: str | None = None,
+    ) -> dict[str, Any]:
         if value is None:
-            return {"encoding": None, "payload_bytes": None, "object_id": object_id}
+            return {
+                "encoding": None,
+                "payload_bytes": None,
+                "object_id": object_id,
+                "server_id": server_id,
+            }
         encoding, payload = serialize_payload(value)
-        return {"encoding": encoding, "payload_bytes": payload, "object_id": object_id}
+        return {
+            "encoding": encoding,
+            "payload_bytes": payload,
+            "object_id": object_id,
+            "server_id": server_id,
+        }
 
     def _encode_endpoint_result(self, result: _EndpointResult) -> dict[str, Any]:
-        return self._encode_result(result.value, object_id=result.object_id)
+        return self._encode_result(
+            result.value,
+            object_id=result.object_id,
+            server_id=self.server_id if result.object_id is not None else None,
+        )
 
     def _task_manager_instance(self) -> TaskManager:
         if self._task_manager is None:
@@ -540,6 +600,44 @@ class SharedTensorServer:
             )
         return self._task_manager
 
+    def invalidate_call_cache(
+        self,
+        endpoint: str,
+        *,
+        args: tuple[Any, ...] = (),
+        kwargs: dict[str, Any] | None = None,
+    ) -> bool:
+        definition = self.provider.get_endpoint(endpoint)
+        resolved_kwargs = kwargs or {}
+        cache_key = self._cache_key(endpoint, definition, args, resolved_kwargs)
+        if cache_key is None:
+            return False
+        invalidated_managed = False
+        if definition.managed:
+            invalidated_managed = self._managed_objects.invalidate_cache_key(cache_key)
+        with self._coordination_lock:
+            removed = self._local_cache.pop(cache_key, None)
+            self._cache.pop(cache_key, None)
+        invalidated = invalidated_managed or removed is not None
+        if invalidated:
+            self.stats["cache_invalidations"] += 1
+        return invalidated
+
+    def invalidate_endpoint_cache(self, endpoint: str) -> int:
+        self.provider.get_endpoint(endpoint)
+        removed = 0
+        with self._coordination_lock:
+            keys = [cache_key for cache_key, cache_endpoint in self._cache.items() if cache_endpoint == endpoint]
+            for cache_key in keys:
+                self._cache.pop(cache_key, None)
+                if cache_key in self._local_cache:
+                    self._local_cache.pop(cache_key, None)
+                    removed += 1
+        removed += self._managed_objects.invalidate_endpoint(endpoint)
+        if removed:
+            self.stats["cache_invalidations"] += removed
+        return removed
+
     @staticmethod
     def _require_task_id(params: dict[str, Any]) -> str:
         task_id = params.get("task_id")
@@ -559,6 +657,7 @@ class SharedTensorServer:
         return {
             "server": "SharedTensorServer",
             "version": _server_version(),
+            "server_id": self.server_id,
             "socket_path": self.socket_path,
             "uptime": uptime,
             "running": self.running,
@@ -567,7 +666,13 @@ class SharedTensorServer:
             "ppid": os.getppid(),
             "device_index": resolve_device_index(self.provider.device_index),
             "process_start_method": self._resolved_process_start_method,
-            "stats": dict(self.stats),
+            "stats": {
+                **dict(self.stats),
+                "cache_entries": len(self._local_cache),
+                "inflight_calls": len(self._inflight),
+                **self._managed_objects.stats(),
+                "task_count": 0 if self._task_manager is None else len(self._task_manager.list()),
+            },
             "capabilities": capability_snapshot(),
             "endpoints": list(self.provider.list_endpoints().keys()),
         }
@@ -737,4 +842,6 @@ class SharedTensorServer:
             return 5
         if isinstance(exc, SharedTensorConfigurationError):
             return 6
+        if isinstance(exc, SharedTensorStaleHandleError):
+            return 8
         return 7

{shared_tensor-0.2.8 → shared_tensor-0.2.10}/shared_tensor.egg-info/SOURCES.txt

@@ -4,7 +4,6 @@ README.md
 pyproject.toml
 shared_tensor/__init__.py
 shared_tensor/async_client.py
-shared_tensor/async_provider.py
 shared_tensor/async_task.py
 shared_tensor/client.py
 shared_tensor/errors.py

shared_tensor-0.2.8/shared_tensor/async_provider.py

@@ -1,97 +0,0 @@
-"""Deprecated compatibility shim for task-oriented provider usage."""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from functools import wraps
-from typing import Any, cast
-
-from shared_tensor.provider import SharedTensorProvider
-
-
-class AsyncSharedTensorProvider(SharedTensorProvider):
-    def register(
-        self,
-        func: Callable[..., Any],
-        *,
-        cache: bool = True,
-        cache_format_key: str | None = None,
-        managed: bool = False,
-        async_default_wait: bool = True,
-        execution: str = "task",
-        concurrency: str = "parallel",
-        singleflight: bool = True,
-        wait: bool | None = None,
-    ) -> Callable[..., Any]:
-        resolved_wait = async_default_wait if wait is None else wait
-        registered = super().register(
-            func,
-            cache=cache,
-            cache_format_key=cache_format_key,
-            managed=managed,
-            async_default_wait=resolved_wait,
-            execution=cast(Any, execution),
-            concurrency=cast(Any, concurrency),
-            singleflight=singleflight,
-        )
-        if self.execution_mode in {"server", "local"}:
-            return registered
-
-        endpoint_name = func.__name__
-
-        @wraps(func)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
-            if resolved_wait:
-                return self.call(endpoint_name, *args, **kwargs)
-            return self.submit(endpoint_name, *args, **kwargs)
-
-        wrapped = cast(Any, wrapper)
-        wrapped.submit_async = lambda *args, **kwargs: self.submit(endpoint_name, *args, **kwargs)
-        wrapped.execute_async = lambda *args, wait=resolved_wait, timeout=None, callback=None, **kwargs: self.execute(
-            endpoint_name,
-            *args,
-            wait=wait,
-            timeout=timeout,
-            callback=callback,
-            **kwargs,
-        )
-        return cast(Callable[..., Any], wrapped)
-
-    def share(
-        self,
-        func: Callable[..., Any] | None = None,
-        *,
-        cache: bool = True,
-        cache_format_key: str | None = None,
-        managed: bool = False,
-        execution: str = "task",
-        concurrency: str = "parallel",
-        singleflight: bool = True,
-        wait: bool | None = None,
-        **_: Any,
-    ) -> Callable[[Callable[..., Any]], Callable[..., Any]] | Callable[..., Any]:
-        if func is not None:
-            return self.register(
-                func,
-                cache=cache,
-                cache_format_key=cache_format_key,
-                managed=managed,
-                execution=execution,
-                concurrency=concurrency,
-                singleflight=singleflight,
-                wait=wait,
-            )
-
-        def decorator(inner: Callable[..., Any]) -> Callable[..., Any]:
-            return self.register(
-                inner,
-                cache=cache,
-                cache_format_key=cache_format_key,
-                managed=managed,
-                execution=execution,
-                concurrency=concurrency,
-                singleflight=singleflight,
-                wait=wait,
-            )
-
-        return decorator