xoscar 0.9.0__cp312-cp312-macosx_10_13_x86_64.whl

xoscar/backends/allocate_strategy.py

@@ -0,0 +1,160 @@
+# Copyright 2022-2023 XProbe Inc.
+# derived from copyright 1999-2021 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from abc import ABC, abstractmethod
+from random import choice
+from typing import Dict, Optional, Tuple
+
+from ..core import ActorRef
+from ..errors import NoIdleSlot
+from ..utils import implements
+from .config import ActorPoolConfig
+from .message import _MessageBase
+
+allocated_value = Tuple["AllocateStrategy", Optional[_MessageBase]]
+allocated_values = Dict[Optional[ActorRef], allocated_value]
+allocated_type = Dict[str, allocated_values]
+
+
+class AllocateStrategy(ABC):
+    __slots__ = ()
+
+    @abstractmethod
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        """
+        Get external address where the actor allocated to.
+
+        Parameters
+        ----------
+        config: ActorPoolConfig
+            Actor pool config.
+        allocated:
+            Already allocated of actor and its strategy.
+
+        Returns
+        -------
+        allocated_address: str
+            External address to allocate.
+        """
+
+
+class AddressSpecified(AllocateStrategy):
+    __slots__ = ("address",)
+
+    def __init__(self, address):
+        self.address = address
+
+    @implements(AllocateStrategy.get_allocated_address)
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        return self.address
+
+
+class MainPool(AllocateStrategy):
+    __slots__ = ()
+
+    @implements(AllocateStrategy.get_allocated_address)
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        # allocate to main process
+        main_process_index = config.get_process_indexes()[0]
+        return config.get_external_address(main_process_index)
+
+
+class Random(AllocateStrategy):
+    __slots__ = ()
+
+    @implements(AllocateStrategy.get_allocated_address)
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        return choice(config.get_external_addresses())
+
+
+class RandomSubPool(AllocateStrategy):
+    __slots__ = ()
+
+    @implements(AllocateStrategy.get_allocated_address)
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        return choice(config.get_external_addresses()[1:])
+
+
+class ProcessIndex(AllocateStrategy):
+    __slots__ = ("process_index",)
+
+    def __init__(self, process_index: int):
+        self.process_index = process_index
+
+    @implements(AllocateStrategy.get_allocated_address)
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        actual_process_index = config.get_process_indexes()[self.process_index]
+        return config.get_pool_config(actual_process_index)["external_address"][0]
+
+
+class RandomLabel(AllocateStrategy):
+    __slots__ = ("label",)
+
+    def __init__(self, label):
+        self.label = label
+
+    @implements(AllocateStrategy.get_allocated_address)
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        return choice(config.get_external_addresses(label=self.label))
+
+
+class IdleLabel(AllocateStrategy):
+    __slots__ = "label", "mark"
+
+    def __init__(self, label, mark):
+        self.label = label
+        self.mark = mark
+
+    def __hash__(self):
+        return hash((type(self), self.label, self.mark))
+
+    def __eq__(self, other):
+        return (
+            isinstance(other, IdleLabel)
+            and self.label == other.label
+            and self.mark == other.mark
+        )
+
+    @implements(AllocateStrategy.get_allocated_address)
+    def get_allocated_address(
+        self, config: ActorPoolConfig, allocated: allocated_type
+    ) -> str:
+        addresses = config.get_external_addresses(label=self.label)
+        for addr in addresses:
+            occupied = False
+            for strategy, _ in allocated.get(addr, dict()).values():
+                if strategy == self:
+                    occupied = True
+                    break
+            if not occupied:
+                return addr
+        raise NoIdleSlot(
+            f"No idle slot for creating actor "
+            f"with label {self.label}, mark {self.mark}"
+        )

xoscar/backends/communication/__init__.py

@@ -0,0 +1,30 @@
+# Copyright 2022-2023 XProbe Inc.
+# derived from copyright 1999-2021 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .base import Channel, ChannelType, Client, Server
+from .core import gen_local_address, get_client_type, get_server_type
+from .dummy import DummyChannel, DummyClient, DummyServer
+from .socket import (
+    SocketChannel,
+    SocketClient,
+    SocketServer,
+    UnixSocketClient,
+    UnixSocketServer,
+)
+from .ucx import (  # noqa: F401 # pylint: disable=unused-import
+    UCXChannel,
+    UCXClient,
+    UCXServer,
+)

xoscar/backends/communication/base.py

@@ -0,0 +1,315 @@
+# Copyright 2022-2023 XProbe Inc.
+# derived from copyright 1999-2021 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Callable, Coroutine, Type
+
+from ...utils import classproperty, implements
+
+
+@dataclass
+class ChannelType:
+    local = 0  # for local communication
+    ipc = 1  # inproc
+    remote = 2  # remote
+
+
+class Channel(ABC):
+    """
+    Channel is used to do data exchange between server and client.
+    """
+
+    __slots__ = "local_address", "dest_address", "compression"
+
+    name: str | None = None
+
+    def __init__(
+        self,
+        local_address: str | None = None,
+        dest_address: str | None = None,
+        compression: str | None = None,
+    ):
+        self.local_address = local_address
+        self.dest_address = dest_address
+        self.compression = compression
+
+    @abstractmethod
+    async def send(self, message: Any):
+        """
+        Send data to dest. There should be only one send for one recv, otherwise recv messages
+        may overlap.
+
+        Parameters
+        ----------
+        message:
+            data that sent to dest.
+        """
+
+    @abstractmethod
+    async def recv(self):
+        """
+        Receive data that sent from dest.
+        """
+
+    @abstractmethod
+    async def close(self):
+        """
+        Close channel.
+        """
+
+    @property
+    @abstractmethod
+    def closed(self) -> bool:
+        """
+        This channel is closed or not.
+
+        Returns
+        -------
+        closed:
+            If the channel is closed.
+        """
+
+    @property
+    @abstractmethod
+    def type(self) -> int:
+        """
+        Channel is used for, can be dummy, ipc or remote.
+
+        Returns
+        -------
+        channel_type: int
+            type that can be dummy, ipc or remote.
+        """
+
+    @property
+    def info(self) -> dict:
+        return {
+            "name": self.name,
+            "compression": self.compression,
+            "type": self.type,
+            "local_address": self.local_address,
+            "dest_address": self.dest_address,
+        }
+
+
+class Server(ABC):
+    __slots__ = "address", "channel_handler"
+
+    scheme: str | None = None
+
+    def __init__(
+        self,
+        address: str,
+        channel_handler: Callable[[Channel], Coroutine] | None = None,
+    ):
+        self.address = address
+        self.channel_handler = channel_handler
+
+    @classproperty
+    @abstractmethod
+    def client_type(self) -> Type["Client"]:
+        """
+        Return the corresponding client type.
+
+        Returns
+        -------
+        client_type: type
+            client type.
+        """
+
+    @property
+    @abstractmethod
+    def channel_type(self) -> int:
+        """
+        Channel type, can be dummy, ipc or remote.
+
+        Returns
+        -------
+        channel_type: int
+            type that can be dummy, ipc or remote.
+        """
+
+    @staticmethod
+    @abstractmethod
+    async def create(config: dict) -> "Server":
+        """
+        Create a server instance according to configuration.
+
+        Parameters
+        ----------
+        config: dict
+            configuration about creating a channel.
+
+        Returns
+        -------
+        server: Server
+            a server that waiting for connections from clients.
+        """
+
+    @abstractmethod
+    async def start(self):
+        """
+        Used for listening to port or similar stuff.
+        """
+
+    @abstractmethod
+    async def join(self, timeout=None):
+        """
+        Wait forever until timeout.
+        """
+
+    @abstractmethod
+    async def on_connected(self, *args, **kwargs):
+        """
+        Return a channel when new client connected.
+
+        Returns
+        -------
+        channel: Channel
+            channel for communication
+        """
+
+    @abstractmethod
+    async def stop(self):
+        """
+        Stop the server.
+        """
+
+    @property
+    @abstractmethod
+    def stopped(self) -> bool:
+        """
+        If this server is stopped or not.
+
+        Returns
+        -------
+        if_stopped: bool
+           This server is stopped or not.
+        """
+
+    @property
+    def info(self) -> dict:
+        return {
+            "name": self.scheme,
+            "address": self.address,
+            "channel_type": self.channel_type,
+        }
+
+    @classmethod
+    def parse_config(cls, config: dict) -> dict:
+        # skip parsing config by default
+        return dict()
+
+    async def __aenter__(self):
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.stop()
+
+
+class Client(ABC):
+    __slots__ = "local_address", "dest_address", "channel"
+
+    scheme: str | None = None
+
+    def __init__(
+        self, local_address: str | None, dest_address: str | None, channel: Channel
+    ):
+        self.local_address = local_address
+        self.dest_address = dest_address
+        self.channel = channel
+
+    @property
+    def channel_type(self) -> int:
+        """
+        Channel type, can be dummy, ipc or remote.
+
+        Returns
+        -------
+        channel_type: int
+            type that can be dummy, ipc or remote.
+        """
+        return self.channel.type
+
+    @staticmethod
+    @abstractmethod
+    async def connect(
+        dest_address: str, local_address: str | None = None, **kwargs
+    ) -> "Client":
+        """
+        Create a client that is able to connect to some server.
+
+        Parameters
+        ----------
+        dest_address: str
+            Destination server address that to connect to.
+        local_address: str
+            local address.
+
+        Returns
+        -------
+        client: Client
+            Client that holds a channel to communicate.
+        """
+
+    @classmethod
+    def parse_config(cls, config: dict) -> dict:
+        # skip parsing config by default
+        return dict()
+
+    @implements(Channel.send)
+    async def send(self, message):
+        return await self.channel.send(message)
+
+    @implements(Channel.recv)
+    async def recv(self):
+        return await self.channel.recv()
+
+    async def close(self):
+        """
+        Close connection.
+        """
+        await self.channel.close()
+
+    @property
+    def closed(self) -> bool:
+        """
+        This client is closed or not.
+
+        Returns
+        -------
+        closed: bool
+            If the client is closed.
+        """
+        return self.channel.closed
+
+    @property
+    def info(self) -> dict:
+        return {
+            "local_address": self.local_address,
+            "dest_address": self.dest_address,
+            "channel_name": self.channel.name,
+            "channel_type": self.channel_type,
+        }
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

xoscar/backends/communication/core.py

@@ -0,0 +1,69 @@
+# Copyright 2022-2023 XProbe Inc.
+# derived from copyright 1999-2021 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Type
+from urllib.parse import urlparse
+
+from .base import Client, Server
+
+_scheme_to_client_types: dict[str, Type[Client]] = dict()
+_scheme_to_server_types: dict[str, Type[Server]] = dict()
+
+
+def register_client(client_type: Type[Client]):
+    _scheme_to_client_types[client_type.scheme] = client_type  # type: ignore
+    return client_type
+
+
+def register_server(server_type: Type[Server]):
+    _scheme_to_server_types[server_type.scheme] = server_type  # type: ignore
+    return server_type
+
+
+def _check_scheme(scheme: str | None, types: dict):
+    if scheme == "":
+        scheme = None
+    if scheme not in types:  # pragma: no cover
+        raise ValueError(
+            f"address illegal, address scheme "
+            f"should be one of "
+            f'{", ".join(types)}, '
+            f"got {scheme}"
+        )
+    return scheme
+
+
+def get_scheme(address: str) -> str | None:
+    if "://" not in address:
+        scheme = None
+    else:
+        scheme = urlparse(address).scheme
+    return scheme
+
+
+def get_client_type(address: str) -> Type[Client]:
+    scheme = _check_scheme(get_scheme(address), _scheme_to_client_types)
+    return _scheme_to_client_types[scheme]
+
+
+def get_server_type(address: str) -> Type[Server]:
+    scheme = _check_scheme(get_scheme(address), _scheme_to_server_types)
+    return _scheme_to_server_types[scheme]
+
+
+def gen_local_address(process_index: int) -> str:
+    return f"dummy://{process_index}"