xoscar 0.9.0__cp312-cp312-macosx_10_13_x86_64.whl

xoscar/debug.py

@@ -0,0 +1,188 @@
+# 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.
+
+import asyncio.tasks
+import contextvars
+import json
+import logging
+import os
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import List, Optional, Type  # noqa: F401
+
+from .utils import dataslots
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+@dataslots
+@dataclass
+class MessageTraceItem:
+    uid: str
+    address: str
+    method: str
+
+
+@dataslots
+@dataclass
+class DebugOptions:
+    actor_call_timeout: int = 10
+    process_message_timeout: int = 30
+    actor_lock_timeout: int = 30
+    log_unhandled_errors: bool = True
+    log_cycle_send: bool = True
+
+
+_debug_opts: Optional[DebugOptions] = None
+
+
+def get_debug_options() -> Optional[DebugOptions]:
+    return _debug_opts
+
+
+def set_debug_options(options: Optional[DebugOptions]):
+    global _debug_opts
+    _debug_opts = options
+
+    # deliver debug config to native codes for optimization
+    from .core import set_debug_options as core_set_debug_options
+
+    core_set_debug_options(options)
+
+
+def _reload_debug_opts_from_env(cls: Type):
+    config_str = os.environ.get("DEBUG_OSCAR", "0")
+    if config_str == "0":
+        set_debug_options(None)
+        return
+    config_str = os.environ["DEBUG_OSCAR"]
+    config_json = {} if config_str == "1" else json.loads(config_str)
+    set_debug_options(cls(**config_json))
+
+
+def reload_debug_opts_from_env():
+    _reload_debug_opts_from_env(DebugOptions)
+
+
+async def _log_timeout(timeout, msg, *args, **kwargs):
+    start_time, rnd = time.time(), 1
+    while True:
+        await asyncio.sleep(timeout * rnd)
+        rnd += 1
+        logger.warning(
+            msg + " (timeout for %.4f seconds).",
+            *args,
+            time.time() - start_time,
+            **kwargs,
+        )
+
+
+@contextmanager
+def debug_async_timeout(option_name: str, msg, *args, **kwargs):
+    if _debug_opts is None:
+        yield
+    else:
+        timeout_val = getattr(_debug_opts, option_name, -1)
+        timeout_task = None
+        if timeout_val and timeout_val > 0:
+            timeout_task = asyncio.create_task(
+                _log_timeout(timeout_val, msg, *args, **kwargs)
+            )
+
+        try:
+            yield
+        finally:
+            if timeout_task is not None:
+                timeout_task.cancel()
+
+
+_message_trace_var: contextvars.ContextVar = contextvars.ContextVar(
+    "_message_trace_var"
+)
+
+
+@contextmanager
+def record_message_trace(message):
+    if _debug_opts is None or not _debug_opts.log_cycle_send:
+        yield
+    else:
+        msg_trace = list(message.message_trace or [])
+        msg_trace.append(
+            MessageTraceItem(
+                uid=message.actor_ref.uid,
+                address=message.actor_ref.address,
+                method=message.content[0],
+            )
+        )
+        _message_trace_var.set(msg_trace)
+        try:
+            yield
+        finally:
+            _message_trace_var.set(None)
+
+
+def detect_cycle_send(message, wait_response: bool = True):
+    if _debug_opts is None or not _debug_opts.log_cycle_send or not wait_response:
+        return
+
+    cur_trace = _message_trace_var.get(None) or []  # type: List[MessageTraceItem]
+    message.message_trace = cur_trace
+
+    ref_key = (message.actor_ref.uid, message.actor_ref.address)
+    traced_ref_keys = set((item.uid, item.address) for item in cur_trace)
+    if ref_key in traced_ref_keys:
+        looped_trace = cur_trace + [
+            MessageTraceItem(
+                uid=message.actor_ref.uid,
+                address=message.actor_ref.address,
+                method=message.content[0],
+            )
+        ]
+
+        formatted_trace = "\n    ".join(
+            f"Calling {t.method!r} in actor {t.uid} at {t.address}"
+            for t in looped_trace
+        )
+        logger.warning(
+            "Call cycle detected when sending to actor %s at %s, the trace is\n"
+            "    %s",
+            message.actor_ref.uid,
+            message.actor_ref.address,
+            formatted_trace,
+        )
+
+
+@contextmanager
+def no_message_trace():
+    if _debug_opts is None or not _debug_opts.log_cycle_send:
+        yield
+    else:
+        trace = pop_message_trace()
+        yield
+        set_message_trace(trace)
+
+
+def pop_message_trace():
+    trace = _message_trace_var.get(None)
+    _message_trace_var.set(None)
+    return trace
+
+
+def set_message_trace(message_trace):
+    _message_trace_var.set(message_trace)
+
+
+reload_debug_opts_from_env()

xoscar/driver.py

@@ -0,0 +1,42 @@
+# 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 numbers import Number
+from typing import Dict, Type
+
+
+class BaseActorDriver(ABC):
+    @classmethod
+    @abstractmethod
+    def setup_cluster(cls, address_to_resources: Dict[str, Dict[str, Number]]):
+        """
+        Setup cluster according to given resources,
+        resources is a dict, e.g. {'CPU': 3, 'GPU': 1}
+
+        Parameters
+        ----------
+        address_to_resources: dict
+            resources that required for each node.
+        """
+        pass
+
+
+_backend_driver_cls: Dict[str, Type[BaseActorDriver]] = dict()
+
+
+def register_backend_driver(scheme: str, cls: Type[BaseActorDriver]):
+    assert issubclass(cls, BaseActorDriver)
+    _backend_driver_cls[scheme] = cls

xoscar/errors.py

@@ -0,0 +1,63 @@
+# 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.
+
+
+class XoscarError(Exception):
+    pass
+
+
+class ReconstructWorkerError(XoscarError):
+    pass
+
+
+class ActorPoolNotStarted(XoscarError):
+    pass
+
+
+class ActorNotExist(XoscarError):
+    pass
+
+
+class ActorAlreadyExist(XoscarError):
+    pass
+
+
+class NoIdleSlot(XoscarError):
+    pass
+
+
+class NoFreeSlot(XoscarError):
+    pass
+
+
+class SlotStateError(XoscarError):
+    pass
+
+
+class ServerClosed(XoscarError):
+    pass
+
+
+class CannotCancelTask(XoscarError):
+    pass
+
+
+class SendMessageFailed(XoscarError):
+    pass
+
+
+class Return(XoscarError):
+    def __init__(self, value):
+        self.value = value

xoscar/libcpp.pxd

@@ -0,0 +1,31 @@
+# Copyright 2022-2023 XProbe Inc.
+# derived from copyright 1999-2022 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.
+
+# complementary header for C++ STL libs not included in Cython
+
+from libc.stdint cimport uint_fast64_t
+
+
+cdef extern from "<random>" namespace "std" nogil:
+    cdef cppclass mt19937_64:
+        ctypedef uint_fast64_t result_type
+
+        mt19937_64() except +
+        mt19937_64(result_type seed) except +
+        result_type operator()() except +
+        result_type min() except +
+        result_type max() except +
+        void discard(size_t z) except +
+        void seed(result_type seed) except +

xoscar/metrics/__init__.py

@@ -0,0 +1,21 @@
+# Copyright 2022-2023 XProbe Inc.
+#
+# 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 .api import (
+    Metrics,
+    Percentile,
+    init_metrics,
+    record_time_cost_percentile,
+    shutdown_metrics,
+)

xoscar/metrics/api.py

@@ -0,0 +1,288 @@
+# Copyright 2022-2023 XProbe Inc.
+#
+# 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
+
+import logging
+import time
+import weakref
+from contextlib import contextmanager
+from enum import Enum
+from queue import PriorityQueue
+from typing import Any, Callable, NamedTuple
+
+from .backends.console import console_metric
+from .backends.metric import AbstractMetric
+from .backends.prometheus import prometheus_metric
+
+logger = logging.getLogger(__name__)
+
+_init = False
+_metric_backend = "console"
+_backends_cls = {
+    "console": console_metric,
+    "prometheus": prometheus_metric,
+}
+
+
+_metrics_to_be_initialized: weakref.WeakSet = weakref.WeakSet()
+
+
+def init_metrics(backend="console", config: dict[str, Any] | None = None):
+    global _init
+    if _init is True:
+        return
+
+    backend = backend or "console"
+    if backend not in _backends_cls:
+        raise NotImplementedError(f"Do not support metric backend {backend}")
+    global _metric_backend
+    _metric_backend = backend
+    if _metric_backend == "prometheus":
+        try:
+            from prometheus_client import start_http_server
+
+            from ..utils import get_next_port
+
+            port = config.get("port", 0) if config else 0
+            port = port or get_next_port()
+            start_http_server(port)
+            logger.warning(
+                "Finished startup prometheus http server and port is %d", port
+            )
+        except ImportError:
+            logger.warning(
+                "Failed to start prometheus http server because there is no prometheus_client"
+            )
+    _init = True
+    for m in _metrics_to_be_initialized:
+        cls = getattr(_backends_cls[_metric_backend], m.type)
+        metric = cls(m.name, m.description, m.tag_keys)
+        m.set_metric(metric)
+    logger.debug("Finished initialize the metrics of backend: %s.", _metric_backend)
+
+
+def shutdown_metrics():
+    global _metric_backend
+    _metric_backend = "console"
+    global _init
+    _init = False
+    logger.debug("Shutdown metrics of backend: %s.", _metric_backend)
+
+
+class _MetricWrapper(AbstractMetric):
+    _metric: AbstractMetric | None
+    _log_not_init_error: bool
+
+    def __init__(
+        self,
+        name: str,
+        description: str = "",
+        tag_keys: tuple[str, ...] | None = None,
+        metric_type: str = "Counter",
+    ):
+        self._name = name
+        self._description = description
+        self._tag_keys = tag_keys or tuple()
+        self._type = metric_type
+        self._metric = None
+        self._log_not_init_error = False
+
+    @property
+    def type(self):
+        return self._type
+
+    @property
+    def value(self):
+        assert (
+            self._metric is not None
+        ), "Metric is not initialized, please call `init_metrics()` before using metrics."
+        return self._metric.value
+
+    def set_metric(self, metric):
+        assert metric is not None, "Argument metric is None, please check it."
+        self._metric = metric
+
+    def record(self, value=1, tags: dict[str, str] | None = None):
+        if self._metric is not None:
+            self._metric.record(value, tags)
+        elif not self._log_not_init_error:
+            self._log_not_init_error = True
+            logger.warning(
+                "Metric is not initialized, please call `init_metrics()` before using metrics."
+            )
+
+
+def gen_metric(func):
+    def wrapper(name, descriptions: str = "", tag_keys: tuple[str, ...] | None = None):
+        if _init is True:
+            return func(name, descriptions, tag_keys)
+        else:
+            logger.info(
+                "Metric %s will be initialized when invoking `init_metrics()`.", name
+            )
+            metric = _MetricWrapper(
+                name, descriptions, tag_keys, func.__name__.capitalize()
+            )
+            _metrics_to_be_initialized.add(metric)
+            return metric
+
+    return wrapper
+
+
+class Metrics:
+    """
+    A factory to generate different types of metrics.
+
+    Note:
+        Counter, Meter and Histogram are not thread safe.
+
+    Examples
+    --------
+    >>> c1 = counter('counter1', 'A counter')
+    >>> c1.record(1)
+
+    >>> c2 = counter('counter2', 'A counter', ('service', 'tenant'))
+    >>> c2.record(1, {'service': 'indigen', 'tenant': 'test'})
+
+    >>> g1 = gauge('gauge1')
+    >>> g1.record(1)
+
+    >>> m1 = meter('meter1')
+    >>> m1.record(1)
+
+    >>> h1 = histogram('histogram1')
+    >>> h1.record(1)
+    """
+
+    @staticmethod
+    @gen_metric
+    def counter(name, description: str = "", tag_keys: tuple[str, ...] | None = None):
+        logger.debug(
+            "Initializing a counter with name: %s, tag keys: %s, backend: %s",
+            name,
+            tag_keys,
+            _metric_backend,
+        )
+        return _backends_cls[_metric_backend].Counter(name, description, tag_keys)
+
+    @staticmethod
+    @gen_metric
+    def gauge(name, description: str = "", tag_keys: tuple[str, ...] | None = None):
+        logger.debug(
+            "Initializing a gauge whose name: %s, tag keys: %s, backend: %s",
+            name,
+            tag_keys,
+            _metric_backend,
+        )
+        return _backends_cls[_metric_backend].Gauge(name, description, tag_keys)
+
+    @staticmethod
+    @gen_metric
+    def meter(name, description: str = "", tag_keys: tuple[str, ...] | None = None):
+        logger.debug(
+            "Initializing a meter whose name: %s, tag keys: %s, backend: %s",
+            name,
+            tag_keys,
+            _metric_backend,
+        )
+        return _backends_cls[_metric_backend].Meter(name, description, tag_keys)
+
+    @staticmethod
+    @gen_metric
+    def histogram(name, description: str = "", tag_keys: tuple[str, ...] | None = None):
+        logger.debug(
+            "Initializing a histogram whose name: %s, tag keys: %s, backend: %s",
+            name,
+            tag_keys,
+            _metric_backend,
+        )
+        return _backends_cls[_metric_backend].Histogram(name, description, tag_keys)
+
+
+class Percentile:
+    class PercentileType(Enum):
+        P99 = 1
+        P95 = 2
+        P90 = 3
+
+    _min_heap: PriorityQueue
+
+    def __init__(self, capacity: int, window: int, callback: Callable[[float], None]):
+        self._capacity = capacity
+        self._window = window
+        self._callback = callback
+        self._min_heap = PriorityQueue()
+        self._cur_num = 0
+
+        if capacity <= 0 or window <= 0:
+            raise ValueError(
+                f"capacity or window expect to get a positive integer,"
+                f"but capacity got: {capacity} and window got: {window}"
+            )
+
+    def record_data(self, value):
+        store_value = -1 * value
+        if self._min_heap.qsize() < self._capacity:
+            self._min_heap.put(store_value)
+        else:
+            top_value = self._min_heap.get_nowait()
+            store_value = store_value if top_value < store_value else top_value
+            self._min_heap.put(store_value)
+
+        self._cur_num += 1
+        if self._cur_num % self._window == 0:
+            self._callback(-1 * self._min_heap.get_nowait())
+            self._cur_num = 0
+            self._min_heap = PriorityQueue()
+
+    @classmethod
+    def build_p99(cls, callback: Callable[[float], None], window: int):
+        return cls(int(window * 0.01), window, callback)
+
+    @classmethod
+    def build_p95(cls, callback: Callable[[float], None], window: int):
+        return cls(int(window * 0.05), window, callback)
+
+    @classmethod
+    def build_p90(cls, callback: Callable[[float], None], window: int):
+        return cls(int(window * 0.1), window, callback)
+
+
+_percentile_builder = {
+    Percentile.PercentileType.P99: Percentile.build_p99,
+    Percentile.PercentileType.P95: Percentile.build_p95,
+    Percentile.PercentileType.P90: Percentile.build_p90,
+}
+
+
+class PercentileArg(NamedTuple):
+    percentile_type: Percentile.PercentileType
+    callback: Callable[[float], None]
+    window: int
+
+
+@contextmanager
+def record_time_cost_percentile(percentile_args: list[PercentileArg]):
+    percentile_list = [
+        _percentile_builder[percentile_type](callback, window)
+        for percentile_type, callback, window in percentile_args
+    ]
+    st_time = time.time()
+
+    yield
+
+    cost_time = time.time() - st_time
+    for percentile in percentile_list:
+        percentile.record_data(cost_time)

xoscar/metrics/backends/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2022-2023 XProbe Inc.
+#
+# 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.

xoscar/metrics/backends/console/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2022-2023 XProbe Inc.
+#
+# 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.