callserver 0.1.0__tar.gz

callserver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dexman-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

callserver-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: callserver
+Version: 0.1.0
+Summary: Shared-memory RPC for fast inter-process function calls with numpy arrays.
+Author: dexman-ai
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# callserver
+
+Fast inter-process function calls for Python, with numpy arrays passed through shared memory.
+
+## Overview
+
+`callserver` runs Python functions in another process on the same machine. Large numpy arrays in arguments and return values are moved to shared memory automatically, so they are not pickled or pushed through a pipe. Shared memory is allocated on the first call and reused on every call after that.
+
+It is built for low-latency, high-throughput workloads that need a separate process, such as:
+
+- Real-time robot control
+- Vision processing pipelines
+- Compute and data-intensive workloads that benefit from zero-copy data sharing
+
+**Features**
+
+- Automatic shared memory transfer of large numpy arrays, in both directions
+- Zero-copy transfer with pre-allocated shared memory buffers
+- Synchronous and asynchronous calls, with double-buffering to overlap work
+- Persistent server-side state
+- Runs the server as a child process, or connects to a standalone server over TCP
+
+`callserver` works on a single machine only. It is not meant for distributed execution.
+
+## Installation
+
+```bash
+pip install callserver
+```
+
+Requires Python 3.8+ and numpy.
+
+## Usage
+### Simple Example
+Arrays are transferred via shared memory both ways. No serialization!
+Shared memory is only allocated the first time the RPC is made. Subsequent calls reuse the same buffers.
+```python
+import numpy as np
+from callserver import CallServer
+
+if __name__ == "__main__":
+    # Spawns a child process. np.add runs there; the arrays travel through shared memory.
+    with CallServer("adder") as server:
+        result = np.zeros((1024, 1024))
+        ones = np.ones((1024, 1024))
+        for _ in range(100):
+            result = server.call(np.add, result, ones)
+        print(result[0, 0])  # 100.0
+```
+
+### Server-Side State
+A context passed to the server (instance or callable) holds state for subsequent calls:
+
+```python
+import numpy as np
+from callserver import CallServer
+
+class Accumulator:
+    def __init__(self, shape):
+        self.total = np.zeros(shape)
+
+def accumulate(acc, values):
+    acc.total += values
+    return acc.total
+
+if __name__ == "__main__":
+    # Arguments after the initializer are passed to it on the server.
+    with CallServer("accumulator", Accumulator, (512, 512)) as server:
+        for _ in range(10):
+            total = server.call(accumulate, np.ones((512, 512)))
+        print(total[0, 0])  # 10.0
+```
+
+### Standalone Server
+A server can also run as a separate, long-lived process that clients connect to over TCP. Start it from the command line (the port is required):
+
+```bash
+callserver --port 5000
+```
+
+Then connect by passing a `(name, (address, port))` tuple instead of a name:
+
+```python
+import numpy as np
+from callserver import CallServer
+
+with CallServer(("adder", ("127.0.0.1", 5000))) as server:
+    result = server.call(np.add, np.ones((1024, 1024)), np.ones((1024, 1024)))
+    print(result[0, 0])  # 2.0
+```
+
+The server handles one client at a time and keeps running after a client disconnects. Functions sent to it must be importable by the server process.
+
+> Server-side functions must be defined at module level so they can be pickled. The `if __name__ == "__main__":` guard is required on Windows and macOS, because the child process re-imports the main module.
+
+## Documentation
+
+- [Usage guide](callserver/callserver.md): async calls, double-buffering, pre-allocated buffers, standalone servers, the API reference, and how it works.
+- [Examples](examples): runnable scripts.
+
+| Example | Shows |
+| --- | --- |
+| [simple_call.py](examples/simple_call.py) | Basic synchronous call |
+| [server_state.py](examples/server_state.py) | Server-side state with a context initializer |
+| [async_calls.py](examples/async_calls.py) | Async calls with double-buffering |
+| [preallocated_buffers.py](examples/preallocated_buffers.py) | Zero-copy with pre-allocated shared memory |
+| [standalone_client.py](examples/standalone_client.py) | Connecting to a standalone server |
+
+## Development
+
+```bash
+pip install -e .[test]
+python -m pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

callserver-0.1.0/README.md

@@ -0,0 +1,118 @@
+# callserver
+
+Fast inter-process function calls for Python, with numpy arrays passed through shared memory.
+
+## Overview
+
+`callserver` runs Python functions in another process on the same machine. Large numpy arrays in arguments and return values are moved to shared memory automatically, so they are not pickled or pushed through a pipe. Shared memory is allocated on the first call and reused on every call after that.
+
+It is built for low-latency, high-throughput workloads that need a separate process, such as:
+
+- Real-time robot control
+- Vision processing pipelines
+- Compute and data-intensive workloads that benefit from zero-copy data sharing
+
+**Features**
+
+- Automatic shared memory transfer of large numpy arrays, in both directions
+- Zero-copy transfer with pre-allocated shared memory buffers
+- Synchronous and asynchronous calls, with double-buffering to overlap work
+- Persistent server-side state
+- Runs the server as a child process, or connects to a standalone server over TCP
+
+`callserver` works on a single machine only. It is not meant for distributed execution.
+
+## Installation
+
+```bash
+pip install callserver
+```
+
+Requires Python 3.8+ and numpy.
+
+## Usage
+### Simple Example
+Arrays are transferred via shared memory both ways. No serialization!
+Shared memory is only allocated the first time the RPC is made. Subsequent calls reuse the same buffers.
+```python
+import numpy as np
+from callserver import CallServer
+
+if __name__ == "__main__":
+    # Spawns a child process. np.add runs there; the arrays travel through shared memory.
+    with CallServer("adder") as server:
+        result = np.zeros((1024, 1024))
+        ones = np.ones((1024, 1024))
+        for _ in range(100):
+            result = server.call(np.add, result, ones)
+        print(result[0, 0])  # 100.0
+```
+
+### Server-Side State
+A context passed to the server (instance or callable) holds state for subsequent calls:
+
+```python
+import numpy as np
+from callserver import CallServer
+
+class Accumulator:
+    def __init__(self, shape):
+        self.total = np.zeros(shape)
+
+def accumulate(acc, values):
+    acc.total += values
+    return acc.total
+
+if __name__ == "__main__":
+    # Arguments after the initializer are passed to it on the server.
+    with CallServer("accumulator", Accumulator, (512, 512)) as server:
+        for _ in range(10):
+            total = server.call(accumulate, np.ones((512, 512)))
+        print(total[0, 0])  # 10.0
+```
+
+### Standalone Server
+A server can also run as a separate, long-lived process that clients connect to over TCP. Start it from the command line (the port is required):
+
+```bash
+callserver --port 5000
+```
+
+Then connect by passing a `(name, (address, port))` tuple instead of a name:
+
+```python
+import numpy as np
+from callserver import CallServer
+
+with CallServer(("adder", ("127.0.0.1", 5000))) as server:
+    result = server.call(np.add, np.ones((1024, 1024)), np.ones((1024, 1024)))
+    print(result[0, 0])  # 2.0
+```
+
+The server handles one client at a time and keeps running after a client disconnects. Functions sent to it must be importable by the server process.
+
+> Server-side functions must be defined at module level so they can be pickled. The `if __name__ == "__main__":` guard is required on Windows and macOS, because the child process re-imports the main module.
+
+## Documentation
+
+- [Usage guide](callserver/callserver.md): async calls, double-buffering, pre-allocated buffers, standalone servers, the API reference, and how it works.
+- [Examples](examples): runnable scripts.
+
+| Example | Shows |
+| --- | --- |
+| [simple_call.py](examples/simple_call.py) | Basic synchronous call |
+| [server_state.py](examples/server_state.py) | Server-side state with a context initializer |
+| [async_calls.py](examples/async_calls.py) | Async calls with double-buffering |
+| [preallocated_buffers.py](examples/preallocated_buffers.py) | Zero-copy with pre-allocated shared memory |
+| [standalone_client.py](examples/standalone_client.py) | Connecting to a standalone server |
+
+## Development
+
+```bash
+pip install -e .[test]
+python -m pytest
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

callserver-0.1.0/callserver/__init__.py

@@ -0,0 +1,54 @@
+"""
+Shared-memory RPC module for high-performance inter-process communication.
+
+This module provides an efficient Remote Procedure Call (RPC) mechanism that uses
+shared memory for transferring large numpy arrays between processes on the same machine.
+It is designed for use cases where low-latency, high-throughput data exchange is required,
+such as real-time robot control, vision processing pipelines, or any compute-intensive
+workload that benefits from zero-copy data sharing.
+
+Key Features:
+    - Automatic promotion of large numpy arrays to shared memory for zero-copy transfer
+    - Support for both synchronous and asynchronous calls
+    - Front/back buffer pattern for overlapping computation and communication
+    - Connection to child processes or existing server processes via TCP
+
+Limitations:
+    - Only supports inter-process communication on the same machine (shared memory is local)
+    - Cannot be used for distributed or remote execution across machines
+
+Classes:
+    CallServer: Main client interface for making RPC calls to a server process.
+    AllocationSet: Manages a set of shared memory allocations for a single function.
+    AllocationDescriptor: Descriptor for a shared memory buffer (name, shape, dtype).
+    AllocationSetManager: Manages multiple AllocationSet instances for resource allocation.
+
+Functions:
+    run: Run the server loop, either on a child-process connection or as a
+        standalone TCP server on a given (address, port, authkey) endpoint.
+    run_console: Command-line entry point for running a standalone server.
+
+Example:
+    >>> import numpy as np
+    >>> from callserver import CallServer
+    >>> with CallServer('adder') as server:
+    ...     result = server.call(np.add, np.ones((1024, 1024)), np.ones((1024, 1024)))
+    >>> print(result[0, 0])
+    2.0
+
+For more details, see the callserver.md documentation file.
+"""
+
+from .allocationmanager import AllocationSetManager
+from .allocationset import AllocationDescriptor, AllocationSet
+from .callserver import DEFAULT_AUTHKEY, CallServer, run, run_console
+
+__all__ = [
+    "CallServer",
+    "run",
+    "run_console",
+    "DEFAULT_AUTHKEY",
+    "AllocationSet",
+    "AllocationDescriptor",
+    "AllocationSetManager",
+]

callserver-0.1.0/callserver/__main__.py

@@ -0,0 +1,4 @@
+from .callserver import run_console
+
+if __name__ == "__main__":
+    run_console()

callserver-0.1.0/callserver/allocationmanager.py

@@ -0,0 +1,176 @@
+"""
+AllocationSetManager for managing multiple function allocation sets.
+
+This module provides the AllocationSetManager class which coordinates multiple
+AllocationSet instances for different functions in an RPC workflow.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List, Optional, Union
+
+from .allocationset import AllocationSet
+
+
+class AllocationSetManager:
+    """
+    Manages multiple AllocationSet instances for resource allocation in RPC workflows.
+
+    This class implements a singleton pattern per name, ensuring that all references
+    to the same named manager share state. It supports front- and back-buffering
+    for function arguments, tracks active sets, and handles cleanup.
+
+    The manager provides multiple allocation sets per function to support asynchronous
+    call patterns where one set is being used for a call in progress while another
+    is being prepared for the next call.
+
+    Attributes:
+        _managers: Class-level dict of all manager instances by name.
+
+    Example:
+        >>> manager = AllocationSetManager("my_server")
+        >>> alloc_set = manager.add_allocation_set("my_function")
+        >>> # Add a second set for async double-buffering
+        >>> alloc_set2 = manager.add_allocation_set("my_function")
+    """
+
+    _managers: Dict[str, "AllocationSetManager"] = {}
+
+    def __new__(cls, name: Optional[str] = None) -> "AllocationSetManager":
+        """
+        Return existing manager for the given name, or create a new one.
+
+        Args:
+            name: The unique name for this manager.
+
+        Returns:
+            An AllocationSetManager instance (existing or new).
+        """
+        if name is not None and name in cls._managers:
+            return cls._managers[name]
+        return super().__new__(cls)
+
+    def __init__(self, name: Optional[str] = None) -> None:
+        """
+        Initialize the AllocationSetManager.
+
+        If a manager with the given name already exists, this is a no-op.
+
+        Args:
+            name: The unique name for this manager.
+        """
+        if name is not None and name in AllocationSetManager._managers:
+            return
+        self._name = name
+        self._arg_sets: Dict[str, List[AllocationSet]] = {}
+        self._active_set_ids: Dict[str, int] = {}
+        if self._name is not None:
+            assert (
+                self._name not in AllocationSetManager._managers
+            ), f"An AllocationSetManager with name {self._name} already exists."
+            AllocationSetManager._managers[self._name] = self
+
+    def _make_name(self, fn: Union[Callable, str]) -> str:
+        """
+        Convert a function or string to a string name.
+
+        Args:
+            fn: A callable or string identifier.
+
+        Returns:
+            The function's __name__ attribute, or the string itself.
+        """
+        return fn.__name__ if callable(fn) else fn
+
+    def add_allocation_set(self, fn: Union[Callable, str]) -> AllocationSet:
+        """
+        Add a new AllocationSet for the given function.
+
+        Creates a new allocation set and adds it to the list of sets for the
+        specified function. Multiple sets can be created for double-buffering.
+
+        Args:
+            fn: A callable or string identifier for the function.
+
+        Returns:
+            The newly created AllocationSet.
+        """
+        fn_name = self._make_name(fn)
+        if fn_name not in self._arg_sets:
+            self._arg_sets[fn_name] = []
+            self._active_set_ids[fn_name] = -1
+
+        arg_set = AllocationSet(
+            len(self._arg_sets[fn_name]), f"{self._name}.{fn_name}"
+        )
+        self._arg_sets[fn_name].append(arg_set)
+        return arg_set
+
+    def get_allocation_set(
+        self, fn: Union[Callable, str], idx: Optional[int] = None
+    ) -> AllocationSet:
+        """
+        Get an AllocationSet for the given function.
+
+        If idx is None, rotates to the next allocation set (for double-buffering).
+        If idx is specified, returns or creates the set at that index.
+
+        Args:
+            fn: A callable or string identifier for the function.
+            idx: Optional specific index to retrieve.
+
+        Returns:
+            The requested AllocationSet.
+        """
+        fn_name = self._make_name(fn)
+        if fn_name not in self._arg_sets:
+            self.add_allocation_set(fn_name)
+        if idx is None:
+            idx = self._active_set_ids[fn_name]
+            idx = (1 + idx) % len(self._arg_sets[fn_name])
+            self._active_set_ids[fn_name] = idx
+        else:
+            for i in range(len(self._arg_sets[fn_name]), idx + 1):
+                self.add_allocation_set(fn_name)
+        active_set = self._arg_sets[fn_name][idx]
+        return active_set
+
+    def get_active_id(self, fn: Union[Callable, str]) -> int:
+        """
+        Get the currently active allocation set index for a function.
+
+        Args:
+            fn: A callable or string identifier for the function.
+
+        Returns:
+            The index of the currently active AllocationSet.
+        """
+        fn_name = self._make_name(fn)
+        return self._active_set_ids[fn_name]
+
+    def close(self) -> None:
+        """
+        Release all resources held by all allocation sets.
+
+        Closes all allocation sets for all functions managed by this manager.
+        After calling this method, the manager should not be used.
+        """
+        for arg_set_group in self._arg_sets.values():
+            for arg_set in arg_set_group:
+                arg_set.close()
+        self._arg_sets = {}
+
+    def __del__(self) -> None:
+        """Clean up resources when the manager is garbage collected."""
+        self.close()
+
+
+if __name__ == "__main__":
+    manager = AllocationSetManager("test")
+    manager.add_allocation_set("func1")
+    manager2 = AllocationSetManager("test")
+    assert manager is manager2
+    assert manager2.get_allocation_set("func1") != None
+
+    print("Test passed.")
+