Merge pull request #3013 from finos/fix-circular

Fix examples, docs and imports

Author: texodus

docs/md/how_to/python/multithreading.md

@@ -1,21 +1,41 @@
 # Multi-threading
 
-Perspective's API is thread-safe (safe to call from multiple threads
-concurrently),
+Perspective's API is thread-safe, so methods may be called from different
+threads without additional consideration for safety/exclusivity/correctness. All
+`perspective.Client` and `perspective.Server` API methods release the GIL, which
+can be exploited for parallelism.
 
-Perspective's server API releases the GIL when called (though it may be retained
-for some portion of the `Client` call to encode RPC messages). It also
-dispatches to an internal thread pool for some operations, enabling better
-parallelism and overall better server performance. However, Perspective's Python
-interface itself will still process queries in a single queue. To enable
-parallel query processing, call `set_loop_callback` with a multi-threaded
-executor such as `concurrent.futures.ThreadPoolExecutor`:
+Interally, `perspective.Server` also dispatches to a thread pool for some
+operations, enabling better parallelism and overall better query performance.
+This independent threadpool size can be controlled via
+`perspective.set_num_cpus()`, or the `OMP_NUM_THREADS` environment variable.
 
 ```python
-def perspective_thread():
-    server = perspective.Server()
-    loop = tornado.ioloop.IOLoop()
-    with concurrent.futures.ThreadPoolExecutor() as executor:
-        server.set_loop_callback(loop.run_in_executor, executor)
-        loop.start()
+import perspective
+
+perspective.set_num_cpus(2)
+```
+
+## Server handlers
+
+Perspective's server handler implementations each take an optional `executor`
+constructor argument, which (when provided) will configure the handler to
+process WebSocket `Client` requests on a thread pool.
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+from tornado.web import Application
+from perspective.handlers.tornado import PerspectiveTornadoHandler
+from perspective import Server
+
+args = {"perspective_server": Server(), "executor": ThreadPoolExecutor()}
+
+app = Application(
+    [
+        (r"/websocket", PerspectiveTornadoHandler, args),
+
+        # ...
+
+    ]
+)
 ```

examples/esbuild-remote/build.js

@@ -24,6 +24,7 @@ async function build() {
         loader: {
             ".ttf": "file",
             ".arrow": "file",
+            ".wasm": "file",
         },
         assetNames: "[name]",
     });

examples/esbuild-remote/client/index.js

@@ -12,14 +12,22 @@
 
 import perspective from "@finos/perspective";
 
-import "@finos/perspective-viewer";
+import perspective_viewer from "@finos/perspective-viewer";
 import "@finos/perspective-viewer-datagrid";
 import "@finos/perspective-viewer-d3fc";
 
 import "@finos/perspective-viewer/dist/css/pro-dark.css";
 
 import "./index.css";
 
+import SERVER_WASM from "@finos/perspective/dist/wasm/perspective-server.wasm";
+import CLIENT_WASM from "@finos/perspective-viewer/dist/wasm/perspective-viewer.wasm";
+
+await Promise.all([
+    perspective.init_server(fetch(SERVER_WASM)),
+    perspective_viewer.init_client(fetch(CLIENT_WASM)),
+]);
+
 const viewer = document.createElement("perspective-viewer");
 document.body.append(viewer);
 

examples/python-aiohttp/server.py

@@ -10,11 +10,9 @@
 #  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 #  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import asyncio
 import os
 import os.path
 import logging
-import threading
 
 from aiohttp import web
 
@@ -32,22 +30,13 @@ def perspective_thread(server):
     """Perspective application thread starts its own event loop, and
     adds the table with the name "data_source_one", which will be used
     in the front-end."""
-    psp_loop = asyncio.new_event_loop()
-    client = server.new_local_client(loop_callback=psp_loop.call_soon_threadsafe)
-
-    def init():
-        with open(file_path, mode="rb") as file:
-            client.table(file.read(), index="Row ID", name="data_source_one")
-
-    psp_loop.call_soon_threadsafe(init)
-    psp_loop.run_forever()
 
 
 def make_app():
     server = Server()
-    thread = threading.Thread(target=perspective_thread, args=(server,))
-    thread.daemon = True
-    thread.start()
+    client = server.new_local_client()
+    with open(file_path, mode="rb") as file:
+        client.table(file.read(), index="Row ID", name="data_source_one")
 
     async def websocket_handler(request):
         handler = PerspectiveAIOHTTPHandler(perspective_server=server, request=request)

examples/python-starlette/server.py

@@ -10,11 +10,9 @@
 #  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 #  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-import asyncio
 import os
 import os.path
 import logging
-import threading
 import uvicorn
 
 from fastapi import FastAPI, WebSocket
@@ -35,27 +33,11 @@ def static_node_modules_handler(rest_of_path):
     return FileResponse("../../node_modules/{}".format(rest_of_path))
 
 
-def perspective_thread(server):
-    """Perspective application thread starts its own event loop, and
-    adds the table with the name "data_source_one", which will be used
-    in the front-end."""
-    psp_loop = asyncio.new_event_loop()
-    client = server.new_local_client(loop_callback=psp_loop.call_soon_threadsafe)
-
-    def init():
-        with open(file_path, mode="rb") as file:
-            client.table(file.read(), index="Row ID", name="data_source_one")
-
-    psp_loop.call_soon_threadsafe(init)
-    psp_loop.run_forever()
-
-
 def make_app():
     server = Server()
-
-    thread = threading.Thread(target=perspective_thread, args=(server,))
-    thread.daemon = True
-    thread.start()
+    client = server.new_local_client()
+    with open(file_path, mode="rb") as file:
+        client.table(file.read(), index="Row ID", name="data_source_one")
 
     async def websocket_handler(websocket: WebSocket):
         handler = PerspectiveStarletteHandler(

examples/python-tornado/server.py

@@ -26,14 +26,6 @@
 )
 
 
-async def init_table(client):
-    with open(file_path, mode="rb") as file:
-        data = file.read()
-        table = client.table(data, name="data_source_one")
-        for _ in range(10):
-            table.update(data)
-
-
 def make_app(perspective_server):
     return tornado.web.Application(
         [
@@ -62,6 +54,11 @@ def make_app(perspective_server):
     app.listen(8080)
     logging.critical("Listening on http://localhost:8080")
     loop = tornado.ioloop.IOLoop.current()
-    client = perspective_server.new_local_client(loop_callback=loop.add_callback)
-    loop.call_later(0, init_table, client)
+    client = perspective_server.new_local_client()
+    with open(file_path, mode="rb") as file:
+        data = file.read()
+        table = client.table(data, name="data_source_one")
+        for _ in range(10):
+            table.update(data)
+
     loop.start()

packages/perspective-viewer-d3fc/src/ts/plugin/d3fc_global_styles.ts

@@ -10,23 +10,24 @@
 // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-export const D3FC_GLOBAL_STYLES = [];
-
 // Capture (and restore) `document.querySelector` to prevent D3FC from
 // attaching styles to the document `<head>`.
 export async function init() {
     const old_doc = window.document.querySelector;
+    const stylesheets = [];
+
     // @ts-ignore
     window.document.querySelector = () => {
         return {
             appendChild(elem) {
-                D3FC_GLOBAL_STYLES.push(elem);
+                stylesheets.push(elem);
                 return elem;
             },
         };
     };
 
-    const { register } = await import("./plugin");
+    const { register, createStyleSheets } = await import("./plugin");
     window.document.querySelector = old_doc;
+    createStyleSheets(stylesheets);
     register();
 }

packages/perspective-viewer-d3fc/src/ts/plugin/plugin.ts

@@ -18,7 +18,7 @@ import { HTMLPerspectiveViewerElement } from "@finos/perspective-viewer";
 import type * as psp_types from "@finos/perspective-viewer";
 
 import * as d3 from "d3";
-import { D3FC_GLOBAL_STYLES } from "./d3fc_global_styles";
+
 import { Chart, Settings, Type } from "../types";
 
 const DEFAULT_PLUGIN_SETTINGS = {
@@ -30,17 +30,7 @@ const DEFAULT_PLUGIN_SETTINGS = {
     selectMode: "select",
 };
 
-const styleSheets = [];
-for (const style of D3FC_GLOBAL_STYLES) {
-    const sheet = new CSSStyleSheet();
-    sheet.replaceSync(style.textContent);
-    styleSheets.push(sheet);
-}
-
-const sheet = new CSSStyleSheet();
-sheet.replaceSync(style);
-
-styleSheets.push(sheet);
+const D3FC_GLOBAL_STYLES = [];
 
 const EXCLUDED_SETTINGS = [
     "crossValues",
@@ -63,6 +53,18 @@ async function register_element(plugin_name: string) {
     await perspectiveViewerClass.registerPlugin(plugin_name);
 }
 
+export function createStyleSheets(sheets) {
+    for (const style of sheets) {
+        const sheet = new CSSStyleSheet();
+        sheet.replaceSync(style.textContent);
+        D3FC_GLOBAL_STYLES.push(sheet);
+    }
+
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(style);
+    D3FC_GLOBAL_STYLES.push(sheet);
+}
+
 export function register(...plugin_names: string[]) {
     const plugins = new Set(
         plugin_names.length > 0
@@ -115,7 +117,7 @@ class HTMLPerspectiveViewerD3fcPluginElement extends HTMLElement {
     connectedCallback() {
         if (!this._initialized) {
             this.attachShadow({ mode: "open" });
-            for (const sheet of styleSheets) {
+            for (const sheet of D3FC_GLOBAL_STYLES) {
                 this.shadowRoot.adoptedStyleSheets.push(sheet);
             }
 

packages/perspective-viewer-datagrid/src/js/custom_elements/datagrid.js

@@ -23,21 +23,36 @@ import { format_raw } from "../data_listener/format_cell.js";
  * The custom element class for this plugin.  The interface methods for this
  */
 export class HTMLPerspectiveViewerDatagridPluginElement extends HTMLElement {
+    static global_stylesheet_installed = false;
+    static renderTarget =
+        window.CSS?.supports &&
+        window.CSS?.supports("selector(:host-context(foo))")
+            ? "shadow"
+            : "light";
+
+    static #sheet;
+
     constructor() {
         super();
         this.regular_table = document.createElement("regular-table");
         this.regular_table.part = "regular-table";
         this._is_scroll_lock = false;
         this._edit_mode = "READ_ONLY";
         const Elem = HTMLPerspectiveViewerDatagridPluginElement;
-        if (Elem.renderTarget == "shadow") {
-            if (!Elem.#sheet) {
-                Elem.#sheet = new CSSStyleSheet();
-                Elem.#sheet.replaceSync(datagridStyles);
-            }
+        if (!Elem.#sheet) {
+            Elem.#sheet = new CSSStyleSheet();
+            Elem.#sheet.replaceSync(datagridStyles);
+        }
 
+        if (Elem.renderTarget === "shadow") {
             const shadow = this.attachShadow({ mode: "open" });
             shadow.adoptedStyleSheets.push(Elem.#sheet);
+        } else if (
+            Elem.renderTarget === "light" &&
+            !Elem.global_stylesheet_installed
+        ) {
+            Elem.global_stylesheet_installed = true;
+            document.adoptedStyleSheets.push(Elem.#sheet);
         }
     }
 
@@ -177,11 +192,4 @@ export class HTMLPerspectiveViewerDatagridPluginElement extends HTMLElement {
         }
         this.regular_table.clear();
     }
-
-    static renderTarget =
-        window.CSS?.supports &&
-        window.CSS?.supports("selector(:host-context(foo))")
-            ? "shadow"
-            : "light";
-    static #sheet;
 }

rust/perspective-python/Cargo.toml

@@ -22,7 +22,6 @@ authors = ["Andrew Stein <steinlink@gmail.com>"]
 keywords = []
 build = "build.rs"
 include = [
-    "bench/**/*.py",
     "build.rs",
     "./Cargo.toml",
     "LICENSE.md",