pyxllib 0.0.43__py3-none-any.whl → 0.3.197__py3-none-any.whl

pyxllib/file/xlsyncfile.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# @Author : 陈坤泽
+# @Email  : 877362867@qq.com
+# @Date   : 2024/10/12
+
+"""
+我们自己的一套利用后端服务进行文件同步的工具
+"""
+
+import os
+import time
+
+from loguru import logger
+from tqdm import tqdm
+import requests
+
+from pyxllib.file.specialist import XlPath, GetEtag
+from pyxllib.prog.pupil import format_exception
+
+
+class SyncFileClient:
+    """
+
+    注意：该类填写的路径，一律是相对local_root、remote_root的路径，不是当前实际工作目录下的路径！
+        可以通过把local_host设为空的来实现一些特殊精细化的操作
+        但一般推荐还是都把local_root、remote_root设置上
+    """
+
+    def __1_basic(self):
+        pass
+
+    def __init__(self, host, token=None):
+        """
+        :param host: 可以只写主机名
+        """
+        token = token or os.getenv("XL_COMMON_SERVER_TOKEN")
+        self.headers = {
+            'Authorization': f'Bearer {token}',
+        }
+        self.local_root = None
+        self.remote_root = None
+        self.host = self.link_host(host)
+
+    def link_host(self, hostname):
+        from requests.exceptions import Timeout
+
+        host = f'{os.getenv("MAIN_WEBSITE")}/{hostname}'
+        resp = requests.get(f'{host}/common/get_local_server', headers=self.headers)
+        ip = resp.json()['ip']
+
+        if ip:
+            try:
+                resp = requests.get(f'{ip}/healthz', timeout=5)
+                if resp.status_code == 200 and resp.json()['status'] == 'ok':
+                    host = ip
+            except Timeout:
+                pass
+            except Exception as e:
+                raise e
+
+        remote_root = requests.get(f'{host}/common/get_wkdir', headers=self.headers).json()['wkdir']
+        self.remote_root = XlPath(remote_root)
+
+        return host
+
+    def get_abs_local_path(self, local_path, remote_path=None):
+        # 1 如果需要，从远程路径推测本地路径
+        if local_path is None and remote_path is not None:
+            local_path = remote_path
+
+        # 2 本地存储的文件路径
+        if self.local_root:
+            return self.local_root / local_path
+        else:
+            return XlPath(local_path)
+
+    def get_abs_remote_path(self, remote_path, local_path=None):
+        # 1 如果需要，从本地路径推测远程路径
+        if remote_path is None and local_path is not None:
+            remote_path = local_path
+
+        # 2 远程存储的文件路径
+        if self.remote_root:
+            return self.remote_root / remote_path
+        else:
+            return XlPath(remote_path)
+
+    def __2_sync(self):
+        pass
+
+    def upload_file(self, local_file=None, remote_file=None, relpath=True):
+        """
+        :param str remote_file: 要存储的远程文件路径，默认可以不指定，自动通过local_file存储到对称位置
+
+        使用示例：
+        sfc = SyncFileClient('codepc_mi15')
+        sfc.upload_file('abc/README.md')
+        sfc.upload_file('abc/README.md', 'bcd/1.md')
+        """
+        file = [local_file]
+        if remote_file:
+            file.append(remote_file)
+        return self.upload_files([file], relpath=relpath)
+
+    def upload_files(self, files, relpath=True):
+        """
+        :param list[local_file<, remote_path>] files:
+            remote_path可选，未写的时候会自动填充
+        :return:
+
+        todo 加进度条？不过问了下gpt，这个实现好像有点复杂，先不折腾了。本来其实就推荐单个单个文件上传，在外部进行进度展示管控。
+
+        使用示例：
+        sfc = SyncFileClient('codepc_mi15')
+        print(sfc.upload_files(['data/d231120禅宗1期4阶.xlsx', 'data/d231120禅宗1期4阶2.xlsx']))
+        """
+        # 1 映射出目标路径
+        files2 = []
+        for file in files:
+            if not isinstance(file, (list, tuple)):
+                local_file, remote_file = file, None
+            else:
+                local_file, remote_file = file
+
+            if relpath:
+                local_file = self.get_abs_local_path(local_file, remote_file)
+                remote_file = self.get_abs_remote_path(remote_file, local_file)
+
+            files2.append([local_file, remote_file.as_posix()])
+
+        files3 = [('files', (remote_file, open(local_file, 'rb'))) for local_file, remote_file in files2]
+
+        # 4 发送请求
+        resp = requests.post(f'{self.host}/common/upload_files',
+                             headers=self.headers,
+                             files=files3)
+        return resp.json()
+
+    def download_file(self, remote_file=None, local_file=None, relpath=True):
+        """
+        :param str remote_file: 要下载的远程文件路径，相对get_wkdir下的路径
+        :param str local_file: 下载到本地的文件路径，默认可以不指定，自动通过remote_file存储到对称位置
+
+        todo 加进度条？方便超大文件下载查看进度。
+
+        使用示例：
+        sfc = SyncFileClient('http://yourserver.com', headers={"Authorization": "Bearer your_token"})
+        sfc.download_file('.vscode/launch.json', 'launch.json')
+        """
+        if relpath:
+            local_file = self.get_abs_local_path(local_file, remote_file)
+            remote_file = self.get_abs_remote_path(remote_file, local_file)
+
+        data = {'file': remote_file.as_posix()}
+        # 使用 stream=True 开启流式处理
+        with requests.post(f'{self.host}/common/download_file',
+                           headers=self.headers, json=data, stream=True) as resp:
+            if resp.status_code == 200:
+                # 以二进制方式写入文件
+                with open(local_file, 'wb') as f:
+                    # 分块写入文件，每次 1MB (1024 * 1024 bytes)
+                    for chunk in resp.iter_content(chunk_size=1024 * 1024):
+                        if chunk:  # 忽略keep-alive的空块
+                            f.write(chunk)
+                return local_file
+            else:
+                # 处理其他状态码，抛出异常或进行错误处理
+                print(f"Error: Unable to download file, status code {resp.status_code}")
+                return None
+
+    def verify_etag(self, local_file=None, remote_file=None, relpath=True):
+        """
+        :param relpath: 是否使用的是相对路径
+            当不使用relpath的时候，注意local_file、remote_file都是手动必填的XlPath类型字段
+        :return:
+        """
+        if relpath:
+            local_file = self.get_abs_local_path(local_file, remote_file)
+            remote_file = self.get_abs_remote_path(remote_file, local_file)
+        if not local_file.is_file():
+            return {'match': False}
+        local_etag = GetEtag.from_file(local_file)
+        json_data = {'file': remote_file.as_posix(), 'etag': local_etag}
+        resp = requests.post(f'{self.host}/common/check_file_etag',
+                             headers=self.headers,
+                             json=json_data)
+        return resp.json()
+
+    def upload_dir(self,
+                   local_dir=None,
+                   remote_dir=None,
+                   *,
+                   delete_local_file=False,
+                   verify_etag=False,
+                   relpath=True):
+        """
+        :param local_dir: 本地目录
+        :param remote_dir: 远程目录
+        :param delete_local_file: 每个文件上传成功后，是否删除本地文件
+            默认不删除，一般不删除是配合etag校验使用的
+        :param verify_etag: 上传前是否校验etag，如果服务器上对应位置已经有对应etag的文件，其实就不用上传了
+
+        该方法已修改以支持上传子目录和空目录
+        """
+        if relpath:
+            # D:\home\chenkunze\data\temp2，举个具体的例子案例值，供参考理解
+            local_dir = self.get_abs_local_path(local_dir, remote_dir)
+            # /home/chenkunze/data/temp2
+            remote_dir = self.get_abs_remote_path(remote_dir, local_dir)
+
+        for root, dirs, files in os.walk(local_dir):
+            # root拿到的是这样的绝对路径：D:\home\chenkunze\data\temp2\数值问题
+            # '数值问题'
+            subdir = XlPath(root).relpath(local_dir)
+            if not files and not dirs:
+                # 如果该目录为空，则在远程服务器上创建空目录
+                self.create_remote_dir(remote_dir / subdir, relpath=False)
+
+            for file in tqdm(files, desc=f'上传目录：{root}'):
+                local_path = local_dir / subdir / file
+                remote_path = remote_dir / subdir / file
+                if verify_etag and self.verify_etag(local_path, remote_path, relpath=False):
+                    pass  # 如果etag校验通过，跳过上传
+                else:
+                    self.upload_file(local_path, remote_path, relpath=False)
+
+                if delete_local_file:
+                    os.remove(local_path)
+
+    def create_remote_dir(self, remote_dir, relpath=True):
+        """
+        创建远程目录的辅助方法
+        """
+        if relpath:
+            remote_dir = self.get_abs_remote_path(remote_dir)
+        json_data = {'dir': remote_dir.as_posix()}
+        resp = requests.post(f'{self.host}/common/create_dir',
+                             headers=self.headers,
+                             json=json_data)
+        return resp.json()
+
+    def download_dir(self, remote_dir=None, local_dir=None, *, verify_etag=False, relpath=True):
+        """
+        下载远程目录到本地
+        :param remote_dir: 远程目录路径，相对路径或绝对路径都支持
+        :param local_dir: 本地保存目录，默认会自动映射到对应的远程位置
+        :param verify_etag: 是否进行etag校验，跳过已经在本地存在并且未修改的文件
+        :return:
+
+        示例：
+        sfc = SyncFileClient('codepc_mi15')
+        sfc.download_dir('data/temp2')
+        """
+        # 1. 获取绝对路径
+        if relpath:
+            local_dir = self.get_abs_local_path(local_dir, remote_dir)
+            remote_dir = self.get_abs_remote_path(remote_dir, local_dir)
+
+        # 2. 从服务器获取远程目录的文件和子目录结构
+        json_data = {'dir': remote_dir.as_posix()}
+        resp = requests.post(f'{self.host}/common/list_dir', headers=self.headers, json=json_data)
+        if resp.status_code != 200:
+            raise Exception(f"Failed to list remote directory: {resp.text}")
+
+        dir_structure = resp.json()  # 期望返回格式为 {'dirs': [...], 'files': [...]}
+
+        # 3. 创建本地目录
+        if not local_dir.exists():
+            local_dir.mkdir(parents=True)
+
+        # 4. 先处理子目录
+        for subdir in dir_structure.get('dirs', []):
+            local_subdir = local_dir / subdir
+            if not local_subdir.exists():
+                local_subdir.mkdir(parents=True)
+
+            # 递归下载子目录中的文件
+            for i in range(100):  # 开发机senseserver3好像不稳定，加了重试机制
+                try:
+                    self.download_dir(remote_dir / subdir, local_dir / subdir, verify_etag=verify_etag)
+                    break
+                except requests.exceptions.RequestException as e:
+                    logger.warning(format_exception(e, 3))
+                    time.sleep(60)
+                    continue
+            else:
+                raise requests.exceptions.RequestException
+
+        # 5. 下载文件
+        for file in tqdm(dir_structure.get('files', []), desc=f'下载目录：{remote_dir}'):
+            remote_file = remote_dir / file
+            local_file = local_dir / file
+
+            for i in range(100):
+                try:
+                    # 校验etag，如果verify_etag为True并且校验成功，则跳过下载
+                    if verify_etag and self.verify_etag(local_file, remote_file, relpath=False)['match']:
+                        break
+
+                    # 下载文件
+                    logger.info(f'下载文件中：{local_file}')
+                    self.download_file(remote_file, local_file, relpath=False)
+                    break
+                except requests.exceptions.RequestException:
+                    time.sleep(60)
+                    continue
+            else:
+                raise requests.exceptions.RequestException
+
+    def download_path(self, remote_path=None, local_path=None, *, verify_etag=False, relpath=True):
+        """
+        下载远程文件或目录到本地
+        :param remote_path: 远程路径，可以是文件或者目录
+        :param local_path: 本地保存路径，默认会自动映射到对应的远程位置
+        :param verify_etag: 是否进行etag校验，跳过已经在本地存在并且未修改的文件
+        :return:
+        """
+        if relpath:
+            # 获取远程路径的绝对路径
+            remote_path = self.get_abs_remote_path(remote_path, local_path)
+            local_path = self.get_abs_local_path(local_path, remote_path)
+
+        # 判断是文件还是目录
+        json_data = {'path': remote_path.as_posix()}
+        resp = requests.post(f'{self.host}/common/check_path_type', headers=self.headers, json=json_data)
+
+        if resp.status_code != 200:
+            raise Exception(f"Failed to check remote path type: {resp.text}")
+
+        path_info = resp.json()
+
+        if path_info['type'] == 'file':
+            # 如果是文件，调用 download_file
+            self.download_file(remote_file=remote_path, local_file=local_path, relpath=False)
+        elif path_info['type'] == 'dir':
+            # 如果是目录，调用 download_dir
+            self.download_dir(remote_dir=remote_path, local_dir=local_path,
+                              verify_etag=verify_etag, relpath=False)
+        else:
+            raise ValueError(f"Unknown path type: {path_info['type']}")

pyxllib/prog/__init__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# @Author : 陈坤泽
+# @Email  : 877362867@qq.com
+# @Date   : 2021/06/03 21:14

pyxllib/prog/cachetools.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# @Author : 陈坤泽
+# @Email  : 877362867@qq.com
+# @Date   : 2024/05/29
+
+from pyxllib.prog.pupil import check_install_package
+
+# cachetools，通用缓存工具，适用范围更广
+check_install_package('cachetools')
+# cached-property，类属性特用工具，相对比较简洁些
+check_install_package('cached_property', 'cached-property')
+
+# 对于普通函数，一般用lru_cache即可
+from functools import lru_cache
+import threading
+
+from cachetools import cached, LRUCache, TTLCache
+
+# 官方文档：https://pypi.org/project/cached-property/
+from cached_property import cached_property
+from cached_property import threaded_cached_property  # 线程安全
+from cached_property import cached_property_with_ttl  # 限时缓存，单位秒
+from cached_property import threaded_cached_property_with_ttl  # 线程 + 限时
+
+
+# todo 240609周日21:19 https://github.com/awolverp/cachebox，据说这个缓存库速度更快的多
+
+# 进一步封装的更通用、自己常用的装饰器
+
+def xlcache(maxsize=128, *, ttl=None, lock=None, property=False):
+    """ 那些工具接口太复杂难记，自己封装一个统一的工具
+
+    就是一个装饰器，最大缓存多少项，然后是否要开多线程安全，是否要设置限时重置，是否是作为类成员属性修饰
+
+    :param property: 是否作为类成员属性修饰，不过一般不建议通过这里设置，
+        而是外部再加一层@property，不然IDE会识别不了这是一个property，影响开发
+
+    """
+    def decorator(func):
+        if property:
+            if ttl is not None:
+                if lock:
+                    # 使用带有时间限制和线程安全的缓存属性
+                    return threaded_cached_property_with_ttl(ttl)(func)
+                else:
+                    # 使用带有时间限制但非线程安全的缓存属性
+                    return cached_property_with_ttl(ttl)(func)
+            else:
+                if lock:
+                    # 使用线程安全的缓存属性
+                    return threaded_cached_property(func)
+                else:
+                    # 使用普通的缓存属性
+                    return cached_property(func)
+        else:
+            lock2 = threading.RLock() if lock is True else lock
+            if ttl is None:
+                return cached(LRUCache(maxsize), lock=lock2)(func)
+            else:
+                cache = TTLCache(maxsize=maxsize, ttl=ttl)
+                return cached(cache, lock=lock2)(func)
+
+    return decorator

pyxllib/prog/deprecatedlib.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# @Author : 陈坤泽
+# @Email  : 877362867@qq.com
+# @Date   : 2021/06/06 00:50
+
+"""
+原官方库： https://pypi.org/project/Deprecated
+
+其deprecated装饰器的action='once'功能跟我设想的不一样
+
+其实从实际使用角度看，默认的每个物理行只警告一次是最合理的模式，使用起来无伤大雅
+但我非要把这个'once'情景的功能给补完善~~
+
+从 deprecated.classic 文件改编而来
+"""
+
+import functools
+import inspect
+import platform
+import warnings
+
+import wrapt
+
+try:
+    # If the C extension for wrapt was compiled and wrapt/_wrappers.pyd exists, then the
+    # stack level that should be passed to warnings.warn should be 2. However, if using
+    # a pure python wrapt, a extra stacklevel is required.
+    import wrapt._wrappers
+
+    _routine_stacklevel = 2
+    _class_stacklevel = 2
+except ImportError:
+    _routine_stacklevel = 3
+    if platform.python_implementation() == "PyPy":
+        _class_stacklevel = 2
+    else:
+        _class_stacklevel = 3
+
+string_types = (type(b''), type(u''))
+
+
+class ClassicAdapter(wrapt.AdapterFactory):
+    """
+    Classic adapter -- *for advanced usage only*
+
+    This adapter is used to get the deprecation message according to the wrapped object type:
+    class, function, standard method, static method, or class method.
+
+    This is the base class of the :class:`~deprecated.sphinx.SphinxAdapter` class
+    which is used to update the wrapped object docstring.
+
+    You can also inherit this class to change the deprecation message.
+
+    In the following example, we change the message into "The ... is deprecated.":
+
+    .. code-block:: python
+
+       import inspect
+
+       from deprecated.classic import ClassicAdapter
+       from deprecated.classic import deprecated
+
+
+       class MyClassicAdapter(ClassicAdapter):
+           def get_deprecated_msg(self, wrapped, instance):
+               if instance is None:
+                   if inspect.isclass(wrapped):
+                       fmt = "The class {name} is deprecated."
+                   else:
+                       fmt = "The function {name} is deprecated."
+               else:
+                   if inspect.isclass(instance):
+                       fmt = "The class method {name} is deprecated."
+                   else:
+                       fmt = "The method {name} is deprecated."
+               if self.reason:
+                   fmt += " ({reason})"
+               if self.version:
+                   fmt += " -- Deprecated since version {version}."
+               return fmt.format(name=wrapped.__name__,
+                                 reason=self.reason or "",
+                                 version=self.version or "")
+
+    Then, you can use your ``MyClassicAdapter`` class like this in your source code:
+
+    .. code-block:: python
+
+       @deprecated(reason="use another function", adapter_cls=MyClassicAdapter)
+       def some_old_function(x, y):
+           return x + y
+    """
+
+    def __init__(self, reason="", version="", action=None, category=DeprecationWarning):
+        """
+        Construct a wrapper adapter.
+
+        :type  reason: str
+        :param reason:
+            Reason message which documents the deprecation in your library (can be omitted).
+
+        :type  version: str
+        :param version:
+            Version of your project which deprecates this feature.
+            If you follow the `Semantic Versioning <https://semver.org/>`_,
+            the version number has the format "MAJOR.MINOR.PATCH".
+
+        :type  action: str
+        :param action:
+            A warning filter used to activate or not the deprecation warning.
+            Can be one of "error", "ignore", "always", "default", "module", or "once".
+            If ``None`` or empty, the the global filtering mechanism is used.
+            See: `The Warnings Filter`_ in the Python documentation.
+
+        :type  category: type
+        :param category:
+            The warning category to use for the deprecation warning.
+            By default, the category class is :class:`~DeprecationWarning`,
+            you can inherit this class to define your own deprecation warning category.
+        """
+        self.reason = reason or ""
+        self.version = version or ""
+        self.action = action
+        self.category = category
+        super(ClassicAdapter, self).__init__()
+
+    def get_deprecated_msg(self, wrapped, instance):
+        """
+        Get the deprecation warning message for the user.
+
+        :param wrapped: Wrapped class or function.
+
+        :param instance: The object to which the wrapped function was bound when it was called.
+
+        :return: The warning message.
+        """
+        if instance is None:
+            if inspect.isclass(wrapped):
+                fmt = "Call to deprecated class {name}."
+            else:
+                fmt = "Call to deprecated function (or staticmethod) {name}."
+        else:
+            if inspect.isclass(instance):
+                fmt = "Call to deprecated class method {name}."
+            else:
+                fmt = "Call to deprecated method {name}."
+        if self.reason:
+            fmt += " ({reason})"
+        if self.version:
+            fmt += " -- Deprecated since version {version}."
+        return fmt.format(name=wrapped.__name__, reason=self.reason or "", version=self.version or "")
+
+    def __call__(self, wrapped):
+        """
+        Decorate your class or function.
+
+        :param wrapped: Wrapped class or function.
+
+        :return: the decorated class or function.
+
+        .. versionchanged:: 1.2.4
+           Don't pass arguments to :meth:`object.__new__` (other than *cls*).
+
+        .. versionchanged:: 1.2.8
+           The warning filter is not set if the *action* parameter is ``None`` or empty.
+        """
+        if inspect.isclass(wrapped):
+            old_new1 = wrapped.__new__
+
+            def wrapped_cls(cls, *args, **kwargs):
+                msg = self.get_deprecated_msg(wrapped, None)
+                if self.action:
+                    with warnings.catch_warnings():
+                        warnings.simplefilter(self.action, self.category)
+                        warnings.warn(msg, category=self.category, stacklevel=_class_stacklevel)
+                else:
+                    warnings.warn(msg, category=self.category, stacklevel=_class_stacklevel)
+                if old_new1 is object.__new__:
+                    return old_new1(cls)
+                # actually, we don't know the real signature of *old_new1*
+                return old_new1(cls, *args, **kwargs)
+
+            wrapped.__new__ = staticmethod(wrapped_cls)
+
+        return wrapped
+
+
+def deprecated(*args, **kwargs):
+    """
+    """
+    if args and isinstance(args[0], string_types):
+        kwargs['reason'] = args[0]
+        args = args[1:]
+
+    if args and not callable(args[0]):
+        raise TypeError(repr(type(args[0])))
+
+    if args:
+        action = kwargs.get('action')
+        category = kwargs.get('category', DeprecationWarning)
+        adapter_cls = kwargs.pop('adapter_cls', ClassicAdapter)
+        adapter = adapter_cls(**kwargs)
+
+        wrapped = args[0]
+        if inspect.isclass(wrapped):
+            wrapped = adapter(wrapped)
+            return wrapped
+
+        elif inspect.isroutine(wrapped):
+            once = False
+
+            @wrapt.decorator(adapter=adapter)
+            def wrapper_function(wrapped_, instance_, args_, kwargs_):
+                nonlocal once
+                msg = adapter.get_deprecated_msg(wrapped_, instance_)
+                if action:
+                    if action == 'once' and once:
+                        pass
+                    else:
+                        once = True
+                        with warnings.catch_warnings():
+                            warnings.simplefilter(action, category)
+                            warnings.warn(msg, category=category, stacklevel=_routine_stacklevel)
+                else:
+                    warnings.warn(msg, category=category, stacklevel=_routine_stacklevel)
+                return wrapped_(*args_, **kwargs_)
+
+            return wrapper_function(wrapped)
+
+        else:
+            raise TypeError(repr(type(wrapped)))
+
+    return functools.partial(deprecated, **kwargs)

pyxllib/prog/filelock.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# @Author : 陈坤泽
+# @Email  : 877362867@qq.com
+# @Date   : 2024/11/13
+
+import os
+import tempfile
+import time
+
+from filelock import FileLock, Timeout
+
+
+class XlFileLock(FileLock):
+    def __init__(self, lock_file: str, timeout: float = -1, **kwargs):
+        """
+        初始化 XlFileLock 实例，锁文件默认存储在系统临时目录中。
+
+        :param str filename: 锁文件的文件名（不包含路径）。
+        :param float timeout: 获取锁的超时时间（以秒为单位），默认值为 -1 表示无限等待。
+        """
+        lock_file_path = os.path.join(tempfile.gettempdir(), lock_file)
+        super().__init__(lock_file=lock_file_path, timeout=timeout, **kwargs)
+
+
+def get_autoui_lock(lock_file='autoui.lock', timeout=-1):
+    """
+    注意：XlFileLock中的lock_file无法设置默认值，这跟FileLock的底层有关
+        所以无法继承一个AutoUiLock类，但是可以通过这种函数的方式，绕开它特殊的初始化限制
+    """
+    lock = XlFileLock(lock_file=lock_file, timeout=timeout)
+    return lock
+
+
+if __name__ == "__main__":
+    try:
+        with get_autoui_lock(timeout=5):
+            print("Lock acquired, doing some work...")
+            time.sleep(3)
+            print("Work done.")
+    except Timeout:
+        print("Failed to acquire lock within the timeout.")