Merge pull request #377 from sshanks-kx/mtim

2 pages were discussing same thing in different ways

Author: iciobanukx

docs/basics/cmdline.md

@@ -243,7 +243,7 @@ See
 [`\p` system command](syscmds.md#p-listening-port)
 <br>
 :fontawesome-solid-graduation-cap:
-[Multithreaded input mode](../kb/multithreaded-input.md),
+[Multithreaded input mode](listening-port.md#multi-threaded-input-mode),
 [Changes in 3.5](../releases/ChangesIn3.5.md#socket-sharding)
 <br>
 :fontawesome-regular-map:

docs/basics/errors.md

@@ -98,7 +98,7 @@ close
 [](){#con}
 con
 
-:   qcon client is not supported when kdb+ is in [multithreaded input mode](../kb/multithreaded-input.md)
+:   qcon client is not supported when kdb+ is in [multithreaded input mode](listening-port.md#multi-threaded-input-mode)
 
 [](){#cond}
 cond

docs/basics/listening-port.md

@@ -91,11 +91,16 @@ q)\p -2000/2010           / use a free port between 2000 and 2010 in multithread
 q)\p myhost:2000/2010     / use a free port between 2000 and 2010, using given hostname
 ```
 
-## Multi-threaded port
+## Multi-threaded input mode
 
-A negative port sets a [multi-threaded](../kb/multithreaded-input.md) port and if used it must be the initial and only mode of operation, 
+A negative port sets a multi-threaded port and if used it must be the initial and only mode of operation, 
 i.e. do not dynamically switch between positive port and negative port.
 
+When active, each IPC connection will create a new thread for its sole use.
+Each connection uses its own heap with a minimum of 64MB, the real amount depending on the working space required by the query being executed. 
+[`\ts`](syscmds.md#ts-time-and-space) can be used to find the memory requirement of a query.
+It is designed for serving in-memory static data to an externally constrained number of clients. It is not intended for use as a gateway, or serving mutable data.
+
 Note that there are a number of restrictions in multithreaded mode:
 
 * queries are unable to update globals
@@ -104,6 +109,15 @@ Note that there are a number of restrictions in multithreaded mode:
 * [.z.W](../ref/dotz.md#zw-handles) has a view on main thread sockets only
 * Cannot send async message
 * Views can be recalculated from the main thread only
+* Uncompressed pages will not be shared between threads (i.e. same situation as with starting a separate hdb for each request). 
+
+The main thread is allowed to update globals. The main thread is responsible for reading from stdin (i.e. the console) and executing any loaded scripts on start-up.
+It also invokes [.z.ts](../ref/dotz.md#zts-timer) on [timer expiry](syscmds.md#t-timer). 
+Any connections made via IPC from the main thread, can be monitored
+for callbacks (for example via an [async callback](../kb/callbacks.md)) which in turn can update globals.
+While the main thread is processing an update (for example, a timer firing or console input) none of the connection threads will be processing any input.
+Updates should not be frequent, as they wait for completion of exiting queries and block new queries (using multiple-read single-write lock), thus slowing processing speeds. 
+If an attempt is made to update globals from threads other than main, a `'no update` error is issued.
 
 Multithreaded input mode supports WebSockets and HTTP (but not TLS) since 4.1t 2021.03.30. 
 TLS support available since 4.1t 2023.12.14. A custom [.z.ph](../ref/dotz.md#zph-http-get) which does not update global state should be used with HTTP.
@@ -170,6 +184,3 @@ Once you open a port in q session, it is open to all connections, including HTTP
 Command-line options [`-e`](cmdline.md#-e-tls-server-mode),
 [`-p`](cmdline.md#-p-listening-port); 
 system command [`\p`](syscmds.md#p-listening-port)
-<br>
-:fontawesome-solid-graduation-cap:
-[Multithreaded input mode](../kb/multithreaded-input.md)

docs/basics/syscmds.md

@@ -525,7 +525,7 @@ See
 [`-p` command-line option ](cmdline.md#-p-listening-port)
 <br>
 :fontawesome-solid-graduation-cap:
-[Multithreaded input mode](../kb/multithreaded-input.md),
+[Multithreaded input mode](listening-port.md#multi-threaded-input-mode),
 [Changes in 3.5](../releases/ChangesIn3.5.md#socket-sharding)
 <br>
 :fontawesome-regular-map:

docs/cloud/aws/index.md

@@ -284,7 +284,7 @@ The CPU requirement of the real-time database (RDB) comes from
 -   appending updates to local tables
 -   user queries
 
-Local table updates are very efficient especially if TP sends batch updates. Nevertheless, faster CPU results in faster ingestion and lower latency. User queries are often CPU-intensive. They perform aggregation and joins, and call expensive functions. If the RDB is set up in [multithreaded input mode](../../kb/multithreaded-input.md) then user queries are executed in parallel. Furthermore, kdb+ 4.0 supports multithreading in most primitives, including `sum`, `avg`, `dev`, etc. If the RDB process is heavily used and hit by many queries, then it is recommended to start with [secondary threads](../../basics/cmdline.md#-s-secondary-threads). VMs with plenty of cores are recommended for RDB processes with large numbers of user queries.
+Local table updates are very efficient especially if TP sends batch updates. Nevertheless, a faster CPU results in faster ingestion and lower latency. User queries are often CPU-intensive. They perform aggregation and joins, and call expensive functions. If the RDB is set up in [multithreaded input mode](../../basics/listening-port.md#multi-threaded-input-mode) then user queries are executed in parallel. Furthermore, kdb+ 4.0 supports multithreading in most primitives, including `sum`, `avg`, `dev`, etc. If the RDB process is heavily used and hit by many queries, then it is recommended to start with [secondary threads](../../basics/cmdline.md#-s-secondary-threads). VMs with plenty of cores are recommended for RDB processes with large numbers of user queries.
 
 If the infrastructure is sensitive to the RDB EOD work, then powerful CPUs are recommended. Sorting tables before splaying is a CPU-intensive task.
 
@@ -365,7 +365,7 @@ EFA provides lower and more consistent latency and higher throughput than the TC
 
 A network load balancer is a type of [Elastic Load Balancer](https://aws.amazon.com/elasticloadbalancing/) by Amazon. It is used for ultra-high performance, TLS offloading at scale, centralized certificate deployment, support for UDP, and static IP addresses for your application. Operating at the connection level, Network Load Balancers are capable of handling millions of requests per second securely while maintaining ultra-low latencies.
 
-Load balancers can distribute load among applications that offer the same service. kdb+ is single-threaded by default. You can set [multithreaded input mode](../../kb/multithreaded-input.md) in which requests are processed in parallel. This however, is not recommended for gateways (due to socket usage limitation) and for q servers that process data from disk, like HDBs.
+Load balancers can distribute load among applications that offer the same service. kdb+ is single-threaded by default. You can set [multithreaded input mode](../../basics/listening-port.md#multi-threaded-input-mode) in which requests are processed in parallel. This however, is not recommended for gateways (due to socket usage limitation) and for q servers that process data from disk, like HDBs.
 
 A better approach is to use a pool of HDB processes. Distributing the queries can either be done by the gateway via async calls or by a load balancer. If the gateways are sending sync queries to the HDB load balancer, then we recommend a gateway load balancer to avoid query contention in the gateway. Furthermore, there are other tickerplant components that enjoy the benefit of load balancers to handle simultaneous requests better.
 

docs/kb/multithreaded-input.md

@@ -173,7 +173,7 @@ h(reval(value;)enlist@;(key;`$":/home/charlie/db"))
 
 ## :fontawesome-solid-bolt: Multithreaded primitives
 
-kdb+ has been multithreaded for more than 15 years, and users could leverage this explicitly through [`peach`](../ref/each.md), or via the [multithreaded input mode](../kb/multithreaded-input.md).
+kdb+ has been multithreaded for more than 15 years, and users could leverage this explicitly through [`peach`](../ref/each.md), or via the [multithreaded input mode](../basics/listening-port.md#multi-threaded-input-mode).
 
 kdb+ 4.0 adds an additional level of multithreading via primitives.
 It is fully transparent to the user, requiring no code change by the user to exploit it. The underlying framework currently uses the number of threads configured as secondary threads on the command line.

docs/releases/ChangesIn4.0.md

@@ -474,7 +474,6 @@ nav:
       - Coding:
         - Geospatial indexing: kb/geospatial.md
         - Linear programming: kb/lp.md
-        - Multithreaded input: kb/multithreaded-input.md
         - Multithreaded primitives: kb/mt-primitives.md
         - Pivoting tables: kb/pivoting-tables.md
         - Precision: basics/precision.md