Coordination Service experimental support

docs/examples.rst

@@ -5,4 +5,5 @@ Examples
    :maxdepth: 3
 
    examples/basic_example
-   examples/authentication
+   examples/authentication
+   examples/coordination

docs/examples/coordination.rst

@@ -0,0 +1,99 @@
+Coordination Service
+===================
+
+.. warning::
+   Coordination Service API is experimental and may contain bugs and may change in future releases.
+
+All examples in this section are parts of `coordination example <https://github.com/ydb-platform/ydb-python-sdk/tree/main/examples/coordination>`_.
+
+
+Create node
+-----------
+
+.. code-block:: python
+
+    driver.coordination_client.create_node("/local/my_node")
+
+Create node with config
+-----------------------
+
+.. code-block:: python
+
+    from ydb import NodeConfig, ConsistencyMode, RateLimiterCountersMode
+
+    config = NodeConfig(
+        attach_consistency_mode=ConsistencyMode.STRICT,
+        read_consistency_mode=ConsistencyMode.STRICT,
+        rate_limiter_counters_mode=RateLimiterCountersMode.AGGREGATED,
+        self_check_period_millis=1000,
+        session_grace_period_millis=10000
+    )
+
+    driver.coordination_client.create_node("/local/my_node", config)
+
+Describe node
+-------------
+
+.. code-block:: python
+
+    config = driver.coordination_client.describe_node("/local/my_node")
+
+Alter node
+----------
+
+.. code-block:: python
+
+    new_config = NodeConfig(
+        attach_consistency_mode=ConsistencyMode.RELAXED,
+        read_consistency_mode=ConsistencyMode.RELAXED,
+        rate_limiter_counters_mode=RateLimiterCountersMode.DETAILED,
+        self_check_period_millis=2000,
+        session_grace_period_millis=15000
+    )
+    driver.coordination_client.alter_node("/local/my_node", new_config)
+
+Delete node
+-----------
+
+.. code-block:: python
+
+    driver.coordination_client.delete_node("/local/my_node")
+
+Create session
+--------------
+
+.. code-block:: python
+
+    with driver.coordination_client.session("/local/my_node") as session:
+        pass
+
+Use semaphore manually
+----------------------
+
+.. code-block:: python
+
+    with driver.coordination_client.session("/local/my_node") as session:
+        semaphore = session.semaphore("my_semaphore", limit=2)  # limit is optional, default is 1
+        semaphore.acquire(count=2) # count is optional, default is 1
+        try:
+            pass
+        finally:
+            semaphore.release()
+
+Use semaphore with context manager
+----------------------------------
+
+.. code-block:: python
+
+    with driver.coordination_client.session("/local/my_node") as session:
+        with session.semaphore("my_semaphore"):
+            pass
+
+Async usage
+-----------
+
+.. code-block:: python
+
+    async with driver.coordination_client.session("/local/my_node") as session:
+        async with session.semaphore("my_semaphore"):
+            pass

examples/coordination/__main__.py

@@ -0,0 +1,40 @@
+import argparse
+import asyncio
+from example import run as run_sync
+from example_async import run as run_async
+import logging
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        description="""\033[92mYDB coordination example.\x1b[0m\n""",
+    )
+    parser.add_argument("-e", "--endpoint", help="Endpoint url to use", default="grpc://localhost:2136")
+    parser.add_argument("-d", "--database", help="Name of the database to use", default="/local")
+    parser.add_argument("-v", "--verbose", default=False, action="store_true")
+    parser.add_argument("-m", "--mode", default="sync", help="Mode of example: sync or async")
+
+    args = parser.parse_args()
+
+    if args.verbose:
+        logger = logging.getLogger("ydb")
+        logger.setLevel(logging.INFO)
+        logger.addHandler(logging.StreamHandler())
+
+    if args.mode == "sync":
+        print("Running sync example")
+        run_sync(
+            args.endpoint,
+            args.database,
+        )
+    elif args.mode == "async":
+        print("Running async example")
+        asyncio.run(
+            run_async(
+                args.endpoint,
+                args.database,
+            )
+        )
+    else:
+        raise ValueError(f"Unsupported mode: {args.mode}, use one of sync|async")

examples/coordination/example.py

@@ -0,0 +1,57 @@
+import time
+import threading
+import ydb
+
+NODE_PATH = "/local/node_name1"
+SEMAPHORE_NAME = "semaphore"
+
+
+def linear_workload(client, text):
+    session = client.session(NODE_PATH)
+    semaphore = session.semaphore(SEMAPHORE_NAME)
+    for i in range(3):
+        semaphore.acquire()
+        for j in range(3):
+            print(f"{text} iteration {i}-{j}")
+            time.sleep(0.1)
+        semaphore.release()
+        time.sleep(0.05)
+    session.close()
+
+
+def context_manager_workload(client, text):
+    with client.session(NODE_PATH) as session:
+        for i in range(3):
+            with session.semaphore(SEMAPHORE_NAME):
+                for j in range(3):
+                    print(f"{text} iteration {i}-{j}")
+                    time.sleep(0.1)
+            time.sleep(0.05)
+
+
+def run(endpoint, database):
+    with ydb.Driver(
+        endpoint=endpoint,
+        database=database,
+        credentials=ydb.credentials_from_env_variables(),
+        root_certificates=ydb.load_ydb_root_certificate(),
+    ) as driver:
+        driver.wait(timeout=5, fail_fast=True)
+
+        driver.coordination_client.create_node(NODE_PATH)
+
+        threads = []
+
+        for i in range(4):
+            worker_name = f"worker {i+1}"
+            if i < 2:
+                thread = threading.Thread(target=linear_workload, args=(driver.coordination_client, worker_name))
+            else:
+                thread = threading.Thread(
+                    target=context_manager_workload, args=(driver.coordination_client, worker_name)
+                )
+            threads.append(thread)
+            thread.start()
+
+        for thread in threads:
+            thread.join()

examples/coordination/example_async.py

@@ -0,0 +1,47 @@
+import asyncio
+import ydb
+
+NODE_PATH = "/local/node_name1"
+SEMAPHORE_NAME = "semaphore"
+
+
+async def linear_workload(client, text):
+    session = client.session(NODE_PATH)
+    semaphore = session.semaphore(SEMAPHORE_NAME)
+    for i in range(3):
+        await semaphore.acquire()
+        for j in range(3):
+            print(f"{text} iteration {i}-{j}")
+            await asyncio.sleep(0.1)
+        await semaphore.release()
+        await asyncio.sleep(0.05)
+    await session.close()
+
+
+async def context_manager_workload(client, text):
+    async with client.session(NODE_PATH) as session:
+        for i in range(3):
+            async with session.semaphore(SEMAPHORE_NAME):
+                for j in range(3):
+                    print(f"{text} iteration {i}-{j}")
+                    await asyncio.sleep(0.1)
+            await asyncio.sleep(0.05)
+
+
+async def run(endpoint, database):
+    async with ydb.aio.Driver(
+        endpoint=endpoint,
+        database=database,
+        credentials=ydb.credentials_from_env_variables(),
+        root_certificates=ydb.load_ydb_root_certificate(),
+    ) as driver:
+        await driver.wait(timeout=5, fail_fast=True)
+
+        await driver.coordination_client.create_node(NODE_PATH)
+
+        await asyncio.gather(
+            linear_workload(driver.coordination_client, "worker 1"),
+            linear_workload(driver.coordination_client, "worker 2"),
+            context_manager_workload(driver.coordination_client, "worker 3"),
+            context_manager_workload(driver.coordination_client, "worker 4"),
+        )