[API-2326] Initial Asyncio Module PR [1/6] #741

yuce · 2025-09-19T16:56:49Z

This is the initial asyncio support.

Added the asyncio module which contains public asyncio API
Added the internal module and internal/asyncio_ modules, which contains the private asyncio API/implementation.
Added asyncio support for the Map proxy. Currently near cache, transactions, and lock releated-methods are not supported. The near cache support will come in another PR. Transactions will likely not be supported. Locks may need a different design.
I didn't include the API docs, in order to make the PR smaller. I'll add them in another PR.
The following tests are ported from the old API, and they work without changes (besides making them compatible with async/await syntax):
- tests/integration/asyncio/authentication_tests
- tests/integration/asyncio/backup_acks_tests
- tests/integration/asyncio/client_test (one test is not ported, due to its Topic DDS dependency)
- tests/integration/asyncio/proxy/map_test

Most of the code in this PR was duplicated to the internal module by prefixing them with asyncio_. For example ROOT/cluster.py was duplicated/modifed as internal/asyncio_cluster.py

Here is the diff between modules in this PR vs their counterparts in the old API:
https://gist.github.com/yuce/56e79a29a1d4d1d996788381d489c0a4

codecov-commenter · 2025-09-19T17:09:09Z

Codecov Report

❌ Patch coverage is 76.65837% with 563 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.48%. Comparing base (5c7a4d5) to head (a87a5c6).

Files with missing lines	Patch %	Lines
hazelcast/internal/asyncio_connection.py	76.16%	149 Missing ⚠️
hazelcast/internal/asyncio_proxy/map.py	78.26%	125 Missing ⚠️
hazelcast/internal/asyncio_invocation.py	72.41%	80 Missing ⚠️
hazelcast/internal/asyncio_cluster.py	63.88%	65 Missing ⚠️
hazelcast/internal/asyncio_compact.py	32.89%	51 Missing ⚠️
hazelcast/internal/asyncio_listener.py	79.23%	38 Missing ⚠️
hazelcast/asyncio/client.py	84.36%	33 Missing ⚠️
hazelcast/internal/asyncio_proxy/base.py	87.50%	14 Missing ⚠️
hazelcast/internal/asyncio_proxy/manager.py	90.00%	4 Missing ⚠️
hazelcast/internal/asyncio_reactor.py	96.49%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #741      +/-   ##
==========================================
- Coverage   95.33%   93.48%   -1.86%     
==========================================
  Files         378      389      +11     
  Lines       21992    24404    +2412     
==========================================
+ Hits        20967    22815    +1848     
- Misses       1025     1589     +564

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

yuce · 2025-09-26T10:42:46Z

I've added the diff between modules in this PR vs their counterparts in the old API to the PR description.

gbarnett-hz

Had a quick look.

For others: probably easier to use https://difftastic.wilfred.me.uk/introduction.html to make life easier.

Haven't studied the reactor in-detail and associated logic in detail. From the diff it looked like the changes were relatively minor, albeit many of them.

I can review those in-depth if needed (or you cannot find people).

gbarnett-hz · 2025-09-29T09:46:52Z

hazelcast/asyncio/client.py

+    _CLIENT_ID = AtomicInteger()
+
+    @classmethod
+    async def create_and_start(cls, config: Config = None, **kwargs) -> "HazelcastClient":


General note -- I'm sure there are others.

If we're trying to get this API nice w.r.t. typing as well then this will probably show some error by default as None is not applicable for Config. Might be more prominent here as I think this is entry point into client creation.

Same for __init__ -- config: Config | None.

Might be missing something in the diff: in client.py there's a load of documentation -- is it elsewhere, or why omit it for this one? (most likely doc applicable from __init__)

re: Docs, I mentioned that in the PR description:

I didn't include the API docs, in order to make the PR smaller. I'll add them in another PR.

If you use better diff tool it doesn't make a difference. Give that one I mentioned a go.

I can review those in-depth if needed (or you cannot find people).

Yes, please.

At least with PyCharm, the user gets the correct type annotation.
There is this project in case you'd like to try the asyncio module:
https://github.com/yuce/hazelcast-asyncio-sample

In any case, I pushed a PR that adds explicit |None:
baa3bc1

PyCharm may be more forgiving -- I've never used it. pyright or pyrefly are good tools to use to determine compliance to the type invariants specified using type annotations.

We check the typings with mypy.

gbarnett-hz · 2025-09-29T10:07:14Z

hazelcast/asyncio/client.py

+            raise
+        _logger.info("Client started")
+
+    async def get_map(self, name: str) -> Map[KeyType, ValueType]:


Intention is only to support also VC in near (immediate) term?

Map is the only proxy included, in order to make the PR small. Other proxies, except VC, may be excluded from the beta release.

gbarnett-hz · 2025-09-29T10:19:35Z

hazelcast/internal/asyncio_proxy/manager.py

+}
+
+
+class ProxyManager:


Note to others: is in proxy/__init__.py

In the diff that I provided in the description I've shown that, but maybe it wasn't easy to notice.

The diff was not good.

gbarnett-hz · 2025-09-29T10:33:09Z

hazelcast/internal/asyncio_reactor.py

+from hazelcast.internal.asyncio_connection import Connection
+from hazelcast.core import Address
+
+_BUFFER_SIZE = 128000


Best to define centrally if possible given it's used across reactors.

I think they should be independent with each other.

The other constant hasn't been changed for ~4 years, same value.

There's not a big probability that it will change.
But I would either have to import it from hazelcast.reactor, or refactor the code so both the asyncore and the asyncio reactor imported it from a common module.
That either introduces a dependency between those reactor modules, or require changes in the "old" Python code, which I tried to avoid.

gbarnett-hz · 2025-09-29T10:36:50Z

hazelcast/internal/asyncio_reactor.py

+    def shutdown(self):
+        if not self._is_live:
+            return
+        # TODO: cancel tasks


compared to reactor.py is this correct?

start, shutdown are not necessary for the AsyncioReactor.
Removed them in the 3rd PR with this commit:
58783dc

hazelcast/internal/asyncio_connection.py

ihsandemir · 2025-11-14T12:45:13Z

hazelcast/asyncio/client.py

+    _CLIENT_ID = AtomicInteger()
+
+    @classmethod
+    async def create_and_start(cls, config: Config | None = None, **kwargs) -> "HazelcastClient":


At Java this method is named as this:

HazelcastClient.newHazelcastClient()

At C++, I used this:

hazelcast::new_client()

Now for python, it will be yet another different name:

HazelcastClient.create_and_start()

Are these too confusing?

It's also StartNewClientAsync in .net. Also, it's initialized over a factory class.

i would choose the name as new_hazelcast_client to be more consistent and easily understandable by any existing Hazelcast users.

#741 (comment)

gbarnett-hz · 2025-11-20T16:04:27Z

hazelcast/internal/asyncio_connection.py

+            self._cluster_connect_timeout_text,
+            self._max_backoff,
+        )
+        time.sleep(sleep_time)


asyncio.sleep ? called on line 550

I've fixed the WaitStrategy in 91bf1d1

gbarnett-hz · 2025-11-20T16:20:40Z

hazelcast/internal/asyncio_invocation.py

+
+        def callback(future):
+            try:
+                schema = future.result()


does .result() block if it's not ready? is it not something like await future, then future.result() or schema = await future?

No it doesn't block.
Trying to get the result when !future.done() raises an exception.
The fetch_schema_future.add_done_callback(callback) a few lines below makes sure that callback receives a done future.

ihsandemir

will continue to review.

hazelcast/asyncio/__init__.py

ihsandemir · 2025-11-21T09:13:57Z

hazelcast/asyncio/client.py

+    _CLIENT_ID = AtomicInteger()
+
+    @classmethod
+    async def create_and_start(cls, config: Config | None = None, **kwargs) -> "HazelcastClient":


i would choose the name as new_hazelcast_client to be more consistent and easily understandable by any existing Hazelcast users.

hazelcast/asyncio/client.py

yuce · 2025-11-21T09:29:18Z

@ihsandemir #741 (comment) Let's discuss about that on the TDD.

hazelcast/asyncio/client.py

emreyigit · 2025-11-20T13:27:49Z

hazelcast/asyncio/client.py

+
+    @property
+    def name(self) -> str:
+        return self._name


If I remember correctly, the missing docs will be part of next PRs to reduce line of changes here.

hazelcast/internal/asyncio_proxy/base.py

emreyigit · 2025-11-20T13:59:02Z

hazelcast/internal/asyncio_proxy/map.py

+        )
+        return await self._invoke(request, handler)
+
+    async def flush(self) -> None:


Why force_unlock and lock are removed?

hazelcast/internal/asyncio_proxy/map.py

hazelcast/internal/asyncio_proxy/base.py

hazelcast/internal/asyncio_connection.py

tests/integration/asyncio/authentication_tests/authentication_test.py

ihsandemir

Looking at code coverage report #741 (comment), new code is around 76% covered. Will you complete it to 100%?

yuce · 2025-11-24T08:25:19Z

@ihsandemir

Looking at code coverage report #741 (comment), new code is around 76% covered. Will you complete it to 100%?

There are 5 more PRs that port more tests.

emreyigit

I don't have anything left for the first PR, thanks.

gbarnett-hz

Had a few scans -- PR is too large to be that confident. I had a few notes though that I forgot from last time.

gbarnett-hz · 2025-11-27T09:55:52Z

hazelcast/internal/asyncio_proxy/map.py

+            except KeyError:
+                partition_map[partition_id] = [entry]
+
+        async with asyncio.TaskGroup() as tg:  # type: ignore[attr-defined]


How are we handling < 3.11? https://github.com/hazelcast/hazelcast-python-client/blob/master/setup.py

TaskGroup added in 3.11 https://docs.python.org/3.11/library/asyncio-task.html#asyncio.TaskGroup

is it possible to use gather? add created tasks into list then gather the list and handle cancellation+exception handling ourselves? If we catch exception then manually cancel the tasks + then have return_exceptions=True?

Or, use TaskGroup for when >= 3.11. Otherwise, we need to assess impact of removing 3.7 support.

3.7 was left unintentionally.
3.11 is the minimum we'll support.

It's possible to approximate ThreadGroup with `gather, but I think it's best to use it directly to make our code a bit more robust.

What's more difficult -- the analysis to determine EOL'ing 3.7 or the technical compromise?

gbarnett-hz · 2025-11-27T10:16:55Z

hazelcast/internal/asyncio_reactor.py

+    def close(self):
+        self._transport.close()
+
+    def write(self, buf):


can we not just _transport.write(buf)? I think this already does what you do in _write_loop without polling.

No, that causes buf to be written immediately, which is not ideal.
_write_loop tries to collect more data before flushing it.

Is it not this: https://github.com/python/cpython/blob/main/Lib/asyncio/transports.py#L108-L114

This is one of the implementations:
https://github.com/python/cpython/blob/9c4ff8a615af3f1e746fcfe5cdb6af5ddfb3b6a7/Lib/asyncio/selector_events.py#L1071

That looks like it is doing what we want for a non-blocking socket unless I misread something: the send will complete later if the call send on the socket would block.

the send will complete later if the call send on the socket would block.

The problem is, it tries to write the data it gets immediately, no matter how small the data is.
Waiting for a bit for more data to arrive is more efficient.

In my first try, I used _transport.write directly, but then switched to the write loop afterwards, since it was more efficient.
To confirm that again, I did a simple benchmark again today, and in all tries, the throughput when writing directly is worse than the write loop.

What are the performance benefits? IMO it's better to integrate as-is rather than invent what looks to be similar to what they are doing unless the improvements are compelling.

The numbers I got were 15% to 70% worse when I used _transport.write directly.

What they do is not similar.
Note that the asyncore ~~API~~ variant of the client also tries to batch socket writes.

Do you have the results + test you can share? Personally I would go with the _transport.write(...) as it seems to be the idiomatic way unless the difference between approaches when you consider avg + tail latencies is significant.

yuce added 5 commits September 19, 2025 18:17

Initial asyncio commit

cbe98dc

Updates

162fd17

Updates

9931956

Merge branch 'master' into asyncio-module

856e3df

Black

35384bf

yuce added 3 commits September 19, 2025 20:12

Updates

fdda120

Updates

fee5b45

Updates

fc2c38b

yuce requested review from anthony-griffin-dev, emreyigit, gbarnett-hz and ihsandemir September 19, 2025 17:30

yuce added 7 commits September 19, 2025 20:39

Removed docs, include HazelcastClient/Map in public API

1772031

Updates

170cf89

Merge branch 'master' into asyncio-module

539c904

black

22449a8

Ignore incorrect mypy errors

5406bc6

Updates

a417a4a

Updates

d00c480

yuce added this to the 5.6.0 milestone Sep 25, 2025

gbarnett-hz reviewed Sep 29, 2025

View reviewed changes

yuce added 6 commits September 29, 2025 14:42

Annotate optional params

baa3bc1

black

ebfc9e2

Remove update to test util

6928837

black

3e03cbf

black

51ced7a

update

e635b94

yuce changed the title ~~Initial Asyncio Module PR~~ Initial Asyncio Module PR [1/3] Oct 1, 2025

yuce added 2 commits October 2, 2025 12:06

Merge branch 'master' into asyncio-module

a630706

Merge branch 'master' into asyncio-module

6ced889

ihsandemir reviewed Nov 14, 2025

View reviewed changes

yuce changed the title ~~Initial Asyncio Module PR [1/3]~~ Initial Asyncio Module PR [1/4] Nov 17, 2025

yuce changed the title ~~Initial Asyncio Module PR [1/4]~~ Initial Asyncio Module PR [1/5] Nov 19, 2025

yuce changed the title ~~Initial Asyncio Module PR [1/5]~~ Initial Asyncio Module PR [1/6] Nov 20, 2025

gbarnett-hz reviewed Nov 20, 2025

View reviewed changes

Addressed review comment

91bf1d1

ihsandemir reviewed Nov 21, 2025

View reviewed changes

emreyigit reviewed Nov 21, 2025

View reviewed changes

Removed unnecessary code

2128f5e

ihsandemir reviewed Nov 21, 2025

View reviewed changes

hazelcast/internal/asyncio_proxy/base.py Show resolved Hide resolved

hazelcast/internal/asyncio_proxy/base.py Show resolved Hide resolved

hazelcast/internal/asyncio_connection.py Show resolved Hide resolved

hazelcast/internal/asyncio_connection.py Show resolved Hide resolved

ihsandemir reviewed Nov 21, 2025

View reviewed changes

tests/integration/asyncio/authentication_tests/authentication_test.py Show resolved Hide resolved

yuce added 2 commits November 21, 2025 17:10

Add BETA warning

62697e3

Black

a87a5c6

ihsandemir reviewed Nov 24, 2025

View reviewed changes

emreyigit approved these changes Nov 25, 2025

View reviewed changes

ihsandemir approved these changes Nov 26, 2025

View reviewed changes

yuce changed the title ~~Initial Asyncio Module PR [1/6]~~ [API-2326] Initial Asyncio Module PR [1/6] Nov 26, 2025

gbarnett-hz reviewed Nov 27, 2025

View reviewed changes

yuce merged commit f49d8ab into hazelcast:master Nov 28, 2025
11 checks passed

yuce deleted the asyncio-module branch November 28, 2025 09:14

yuce mentioned this pull request Dec 4, 2025

Asyncio Module Ported more tests [3/6] #744

Merged

		}


		class ProxyManager:

[API-2326] Initial Asyncio Module PR [1/6] #741

[API-2326] Initial Asyncio Module PR [1/6] #741

Uh oh!

Conversation

yuce commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

yuce commented Sep 26, 2025

Uh oh!

gbarnett-hz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emreyigit Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gbarnett-hz Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ihsandemir left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yuce commented Sep 19, 2025 •

edited

Loading

codecov-commenter commented Sep 19, 2025 •

edited

Loading

gbarnett-hz left a comment •

edited

Loading

emreyigit Nov 20, 2025 •

edited

Loading

gbarnett-hz Nov 20, 2025 •

edited

Loading