Update examples

V2.38

Author: writePerfectCode

examples/func_registry/README.md

@@ -0,0 +1,31 @@
+# Function Registry Demo
+
+This example demonstrates the `func_registry` library: a type-safe C++ function registration and invocation system.
+
+The registry allows you to register functions with metadata and call them back by name, while the compiler enforces type safety.
+
+## Build
+
+```powershell
+cmake -B build -S .
+cmake --build build --target func_registry_demo
+```
+
+## Run
+
+```powershell
+.\build\func_registry_demo.exe
+```
+
+Linux/macOS:
+
+```bash
+./build/func_registry_demo
+```
+
+## Features Demonstrated
+
+- Register static functions, member functions, and lambdas with descriptions
+- Call functions by name with type-safe return values
+- Support for optional parameters with defaults
+- Print registered function signatures

examples/json_invoke/README.md

@@ -0,0 +1,36 @@
+# JSON Invoke Demo
+
+This example demonstrates the `json_invoke` library: a JSON-based function invocation system that bridges C++ functions with LLM-style tool calling.
+
+Functions are registered and invoked via JSON payloads, supporting:
+- Standard JSON request format
+- LLM-compatible tool call format (matching Claude, ChatGPT conventions)
+- Complex types (structs, arrays, nested objects)
+- Custom type serialization
+
+## Build
+
+```powershell
+cmake -B build -S .
+cmake --build build --target json_invoke_demo
+```
+
+## Run
+
+```powershell
+.\build\json_invoke_demo.exe
+```
+
+Linux/macOS:
+
+```bash
+./build/json_invoke_demo
+```
+
+## Features Demonstrated
+
+- Invoke functions by JSON request with typed parameters
+- Support for LLM tool-call request format with JSON-encoded arguments
+- Serialize and deserialize complex C++ types to/from JSON
+- Invoke functions and get results back as C++ types or JSON
+- Process nested objects and arrays in function arguments

examples/json_stateful/README.md

@@ -0,0 +1,36 @@
+# JSON Stateful Demo
+
+This example demonstrates the `json_session_invoke` library: a stateful object lifecycle system for JSON invocation.
+
+Functions can operate in two modes:
+- **Stateless**: Invoke and return immediately
+- **Stateful**: Create a persistent object handle, call methods on it, then destroy it
+
+The lifecycle of a stateful object is: `create -> method calls -> destroy`.
+
+## Build
+
+```powershell
+cmake -B build -S .
+cmake --build build --target json_stateful_demo
+```
+
+## Run
+
+```powershell
+.\build\json_stateful_demo.exe
+```
+
+Linux/macOS:
+
+```bash
+./build/json_stateful_demo
+```
+
+## Features Demonstrated
+
+- Register stateless functions that invoke immediately
+- Register stateful object types with create/method/destroy lifecycle
+- Serialize stateful handles for transport over HTTP or IPC
+- Mix stateless and stateful operations in the same adapter
+- Thread-safe object lifecycle management

examples/json_tracing/README.md

@@ -0,0 +1,37 @@
+# JSON Tracing Demo
+
+This example demonstrates function call tracing and detailed diagnostic output.
+
+When a trace sink is installed, the adapter emits detailed events for:
+- Function invocation with arguments
+- Execution time
+- Success and failure outcomes
+- Parameter serialization and deserialization
+
+Tracing is useful for debugging, performance analysis, and audit logging.
+
+## Build
+
+```powershell
+cmake -B build -S .
+cmake --build build --target json_tracing_demo
+```
+
+## Run
+
+```powershell
+.\build\json_tracing_demo.exe
+```
+
+Linux/macOS:
+
+```bash
+./build/json_tracing_demo
+```
+
+## Features Demonstrated
+
+- Install a trace sink to observe function invocations
+- Capture success and error traces for debugging
+- Serialize trace events to JSON for analysis
+- Understand call parameters and results through trace output

examples/mcp_http/mcp_http_client_demo.py

@@ -155,21 +155,24 @@ def run_demo(client: McpHttpClient) -> None:
     )
     print("write_file:", extract_text_result(write_response))
 
-    open_response = client.call_tool("create_text_file", {"path": "build/_http_demo_scratch.txt"})
-    handle = json.loads(extract_text_result(open_response))
-    print("create_text_file handle:", json.dumps(handle))
-
-    lines_response = client.call_tool("text_file_lines", {"handle": handle})
-    lines = json.loads(extract_text_result(lines_response))
-    print("text_file_lines:", lines)
-
-    client.call_tool("text_file_replace_line", {"handle": handle, "line_number": 2, "content": "BETA (edited)"})
-    client.call_tool("text_file_append", {"handle": handle, "content": "delta (appended)"})
-
-    save_response = client.call_tool("text_file_save", {"handle": handle})
-    print("text_file_save:", extract_text_result(save_response))
-
-    client.call_tool("destroy_text_file", {"handle": handle})
+    handle = None
+    try:
+        open_response = client.call_tool("create_text_file", {"path": "build/_http_demo_scratch.txt"})
+        handle = json.loads(extract_text_result(open_response))
+        print("create_text_file handle:", json.dumps(handle))
+
+        lines_response = client.call_tool("text_file_lines", {"handle": handle})
+        lines = json.loads(extract_text_result(lines_response))
+        print("text_file_lines:", lines)
+
+        client.call_tool("text_file_replace_line", {"handle": handle, "line_number": 2, "content": "BETA (edited)"})
+        client.call_tool("text_file_append", {"handle": handle, "content": "delta (appended)"})
+
+        save_response = client.call_tool("text_file_save", {"handle": handle})
+        print("text_file_save:", extract_text_result(save_response))
+    finally:
+        if handle is not None:
+            client.call_tool("destroy_text_file", {"handle": handle})
 
     # Verify the edit landed on disk
     read_response = client.call_tool("read_file", {"path": "build/_http_demo_scratch.txt"})

examples/mcp_http/mcp_http_gateway_demo.cpp

@@ -660,11 +660,21 @@ int main(int argc, char** argv)
     try
     {
         std::string host = "127.0.0.1";
-        int port = 8080;
+        int port = 18084;
         std::filesystem::path backend_executable;
         for (int index = 1; index < argc; ++index)
         {
             const std::string arg = argv[index];
+            if (arg == "--help" || arg == "-h")
+            {
+                std::cerr << "Usage: " << (argc > 0 ? argv[0] : "mcp_http_gateway_demo") << " [options]\n\n"
+                          << "Options:\n"
+                          << "  --host <address>          HTTP listen address (default: 127.0.0.1)\n"
+                          << "  --port <port>             HTTP listen port (default: 18084, valid: 1-65535)\n"
+                          << "  --backend-executable <path> Path to stdio MCP backend (required if auto-detect fails)\n"
+                          << "  --help, -h                Show this help message\n";
+                return 0;
+            }
             if (arg == "--host" && index + 1 < argc)
             {
                 host = argv[++index];
@@ -673,7 +683,16 @@ int main(int argc, char** argv)
 
             if (arg == "--port" && index + 1 < argc)
             {
-                port = parsePort(argv[++index]);
+                try {
+                    port = parsePort(argv[++index]);
+                    if (port < 1 || port > 65535)
+                    {
+                        throw std::runtime_error("port must be between 1 and 65535");
+                    }
+                } catch (const std::exception& e) {
+                    std::cerr << "Invalid port: " << e.what() << std::endl;
+                    return 1;
+                }
                 continue;
             }
 
@@ -682,6 +701,10 @@ int main(int argc, char** argv)
                 backend_executable = argv[++index];
                 continue;
             }
+
+            std::cerr << "unknown option: " << arg << std::endl;
+            std::cerr << "use --help for usage information." << std::endl;
+            return 1;
         }
 
         const std::filesystem::path resolved_backend = resolveBackendExecutable(backend_executable, argc > 0 ? argv[0] : "");

examples/mcp_http/run_deepseek_mcp_http_chat.py

@@ -89,7 +89,13 @@ def call_mcp_tool(client: McpHttpClient, tool_call: dict[str, Any]) -> str:
     function = tool_call.get("function", {})
     tool_name = function.get("name", "")
     arguments_text = function.get("arguments", "")
-    arguments = json.loads(arguments_text) if arguments_text else {}
+    try:
+        arguments = json.loads(arguments_text) if arguments_text else {}
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            f"Failed to parse arguments for tool '{tool_name}': {exc}. "
+            f"Raw arguments text: {repr(arguments_text)}"
+        ) from exc
     response = client.call_tool(tool_name, arguments)
     return extract_text_result(response)
 

examples/task_scheduler/README.md

@@ -0,0 +1,39 @@
+# Task Scheduler Demo
+
+This example demonstrates the `task_scheduler` library: a priority-based task execution scheduler.
+
+The scheduler manages concurrent execution of function invocations with different priority levels:
+- **FreeReadOnly**: Read-only operations that can run in parallel
+- **ObjectExclusive**: Operations that exclusively lock one object
+- **FactoryLane**: Object creation operations
+- **ToolExclusive**: Exclusive tool access
+- **SessionBarrier**: Session-level synchronization points
+
+This pattern is useful for MCP servers handling concurrent client requests.
+
+## Build
+
+```powershell
+cmake -B build -S .
+cmake --build build --target task_scheduler_demo
+```
+
+## Run
+
+```powershell
+.\build\task_scheduler_demo.exe
+```
+
+Linux/macOS:
+
+```bash
+./build/task_scheduler_demo
+```
+
+## Features Demonstrated
+
+- Submit requests with different scheduling categories
+- Observe concurrent execution of read-only operations
+- Ensure exclusive access for object mutation
+- Track scheduling timing and thread assignment
+- Use futures to wait for results across threads

examples/trace_recorder/README.md

@@ -0,0 +1,38 @@
+# Trace Recorder Demo
+
+This example demonstrates the `trace_recorder` library: an in-memory recording system for function call traces.
+
+Instead of streaming traces to a sink, the `VectorTraceRecorder` buffers all trace events and can export them as a JSON array for inspection or analysis.
+
+This is useful for:
+- Logging complete execution traces for debugging
+- Collecting performance metrics
+- Auditing function calls for compliance
+- Integration with external tracing systems
+
+## Build
+
+```powershell
+cmake -B build -S .
+cmake --build build --target trace_recorder_demo
+```
+
+## Run
+
+```powershell
+.\build\trace_recorder_demo.exe
+```
+
+Linux/macOS:
+
+```bash
+./build/trace_recorder_demo
+```
+
+## Features Demonstrated
+
+- Record all function invocations and results
+- Export recorded traces as structured JSON
+- Clear trace buffer between operations
+- Inspect both successful and failed function calls
+- Analyze serialization and performance timing