Add initial examples.

Author: rlubke

examples/basic/README.md

@@ -0,0 +1,8 @@
+# Basic Examples
+
+These examples demonstrate basic operations against a NamedMap.
+
+To run:
+```bash
+python3 <example-name>
+```

examples/basic/crud.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2023, Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at
+# https://oss.oracle.com/licenses/upl.
+
+import asyncio
+
+from coherence import NamedMap, Session
+
+
+async def do_run() -> None:
+    """
+    Demonstrates basic CRUD operations against a NamedMap using
+    `int` keys and `str` values.
+
+    :return: None
+    """
+    session: Session = Session()
+    try:
+        namedMap: NamedMap[int, str] = await session.get_map("my-map")
+
+        print("Put key 1; value one")
+        await namedMap.put(1, "one")
+
+        print("Value for key 1 is : " + str(await namedMap.get(1)))
+
+        print("NamedMap size is : " + str(await namedMap.size()))
+
+        print("Updating value of key 1 to ONE from " + await namedMap.put(1, "ONE"))
+
+        print("Value for key 1 is : " + str(await namedMap.get(1)))
+
+        print("Removing key 1, current value : " + await namedMap.remove(1))
+
+        print("NamedMap size is : " + str(await namedMap.size()))
+    finally:
+        await session.close()
+
+
+asyncio.run(do_run())

examples/basic/python_object_keys.py

@@ -0,0 +1,56 @@
+import asyncio
+from dataclasses import dataclass
+
+from coherence import NamedMap, Processors, Session
+
+
+@dataclass
+class AccountKey:
+    accountId: int
+    accountType: str
+
+
+@dataclass
+class Account:
+    accountId: int
+    accountType: str
+    name: str
+    balance: float
+
+
+async def do_run() -> None:
+    """
+    Demonstrates basic CRUD operations against a NamedMap using
+    `AccountKey` keys with `Account` values.
+
+    :return: None
+    """
+    session: Session = Session()
+    try:
+        namedMap: NamedMap[AccountKey, Account] = await session.get_map("accounts")
+
+        await namedMap.clear()
+
+        new_account_key: AccountKey = AccountKey(100, "savings")
+        new_account: Account = Account(new_account_key.accountId, new_account_key.accountType, "John Doe", 100000.00)
+
+        print(f"Add new account {new_account} with key {new_account_key}")
+        await namedMap.put(new_account_key, new_account)
+
+        print("NamedMap size is : " + str(await namedMap.size()))
+
+        print("Account from get() : " + str(await namedMap.get(new_account_key)))
+
+        print("Update account balance using processor ...")
+        await namedMap.invoke(new_account_key, Processors.update("balance", new_account.balance + 1000))
+
+        print("Updated account is : " + str(await namedMap.get(new_account_key)))
+
+        await namedMap.remove(new_account_key)
+
+        print("NamedMap size is : " + str(await namedMap.size()))
+    finally:
+        await session.close()
+
+
+asyncio.run(do_run())

examples/basic/python_object_values.py

@@ -0,0 +1,51 @@
+import asyncio
+from dataclasses import dataclass
+
+from coherence import NamedMap, Processors, Session
+
+
+@dataclass
+class Person:
+    """
+    A simple class representing a person.
+    """
+
+    id: int
+    name: str
+    age: int
+
+
+async def do_run() -> None:
+    """
+    Demonstrates basic CRUD operations against a NamedMap using
+    `int` keys and a custom python type, Person, as the value.
+
+    :return: None
+    """
+    session: Session = Session()
+    try:
+        namedMap: NamedMap[int, Person] = await session.get_map("people")
+
+        await namedMap.clear()
+
+        person: Person = Person(1, "Bilbo", 111)
+        print("Add new person : " + str(person))
+        await namedMap.put(person.id, person)
+
+        print("NamedMap size is : " + str(await namedMap.size()))
+
+        print("Person from get() : " + str(await namedMap.get(person.id)))
+
+        print("Update person using processor ...")
+        await namedMap.invoke(person.id, Processors.update("age", 112))
+
+        print("Updated person is : " + str(await namedMap.get(person.id)))
+
+        await namedMap.remove(person.id)
+
+        print("NamedMap size is : " + str(await namedMap.size()))
+    finally:
+        await session.close()
+
+
+asyncio.run(do_run())

src/coherence/client.py

@@ -8,6 +8,7 @@
 import asyncio
 import os
 from asyncio import Task
+from threading import Lock
 from typing import (
     Any,
     AsyncIterator,
@@ -1037,6 +1038,7 @@ def __init__(self, session_options: Optional[Options] = None):
         """
         self._closed: bool = False
         self._caches: dict[str, NamedCache[Any, Any]] = dict()
+        self._lock: Lock = Lock()
         if session_options is not None:
             self._session_options = session_options
         else:
@@ -1159,14 +1161,37 @@ async def get_cache(self, name: str, ser_format: str = DEFAULT_FORMAT) -> "Named
         :return: Returns a :func:`coherence.client.NamedCache` for the specified cache name.
         """
         serializer = SerializerRegistry.serializer(ser_format)
-        c = self._caches.get(name)
-        if c is None:
-            c = NamedCacheClient(name, self, serializer)
-            # initialize the event stream now to ensure lifecycle listeners will work as expected
-            await c._events_manager._ensure_stream()
-            self._setup_event_handlers(c)
-            self._caches.update({name: c})
-        return c
+        with self._lock:
+            c = self._caches.get(name)
+            if c is None:
+                c = NamedCacheClient(name, self, serializer)
+                # initialize the event stream now to ensure lifecycle listeners will work as expected
+                await c._events_manager._ensure_stream()
+                self._setup_event_handlers(c)
+                self._caches.update({name: c})
+            return c
+
+    # noinspection PyProtectedMember
+    @_pre_call_session
+    async def get_map(self, name: str, ser_format: str = DEFAULT_FORMAT) -> "NamedMap[K, V]":
+        """
+        Returns a :func:`coherence.client.NameMap` for the specified cache name.
+
+        :param name: the map name
+        :param ser_format: the serialization format for keys and values stored within the cache
+
+        :return: Returns a :func:`coherence.client.NamedMap` for the specified cache name.
+        """
+        serializer = SerializerRegistry.serializer(ser_format)
+        with self._lock:
+            c = self._caches.get(name)
+            if c is None:
+                c = NamedCacheClient(name, self, serializer)
+                # initialize the event stream now to ensure lifecycle listeners will work as expected
+                await c._events_manager._ensure_stream()
+                self._setup_event_handlers(c)
+                self._caches.update({name: c})
+            return c
 
     # noinspection PyUnresolvedReferences
     async def close(self) -> None: