jquery-connection-pool

Arguments: &key lisp-ports java-ports wait

This operator was added in a patch release in late July, 2013. That patch upgraded jlinker to version 7.1. See jlinker.htm for more information on the patch and version 7.1.

This function allows you to query the state of connection pool intitialization, perhaps waiting until some state is reached. Since the connection pool is created in parallel with the application running after jlinker-init has returned, all the features and benefits of the pool will be available only after some time has passed. If the application requires these features before it can operate correctly, the application should wait until the desired state is reached.

Connection pools are created if the connection-pool argument to jlinker-init is non-nil. That argument (or, if the value of that argument is :delay, the value of the similar argument to jstart-connection-pool) specifies, among other things, the number of Lisp ports to Java and the number of Java ports to Lisp. The state information returned (as two mustiple values described below) provides information on the state of the connection pool and the various ports.

If the wait argument is nil or 0, return immediately. If the wait argument is a positive number, wait at most that many seconds. Otherwise (wait is some non-nil value other than 0 or a positive number), wait until the specified state is reached.

The state is specified by the lisp-ports and java-ports arguments. A positive integer value for either says the specified state is when that number of ports are available (Java to Lisp ports for java-ports, Lisp to Java ports for lisp-ports).

Here are some examples of possible arguments and their meanings:

(jquery-connection-pool :wait nil) ;; return information immediately
                                   ;; the first return value will be T
                                   ;; since lisp-ports and java-ports 
                                   ;; both default to NIL
(jquery-connection-pool :wait nil :lisp-ports 5)
           ;; return immediately. First value T if 5 (or more) Lisp to Java
           ;; ports are available, NIL if less than 5 are available.
(jquery-connection-pool :wait nil :lisp-ports 5 :java-ports 4)
           ;; return immediately. First value T if 5 (or more) Lisp to Java
           ;; ports are available and 4 (or more) Java to Lisp ports
           ;; are available NIL if either less than 5 Lisp to Java or
           ;; less than 4 Java to Lisp ports are available.
(jquery-connection-pool :wait t :lisp-ports 5 :java-ports 4)
           ;; wait until at least 5 Lisp to Java ports are available and
           ;; at least 4 Java to Lisp ports are available.
(jquery-connection-pool :wait 20 :lisp-ports 5 :java-ports 4)
           ;; wait up to 20 seconds until at least 5 Lisp to Java ports 
           ;; are available and at least 4 Java to Lisp ports are available.
           ;; After 20 seconds, act as if :wait were NIL.

lisp-ports and java-ports can be nil (the default in both cases) or a positive integer, which must be less than or equal to the number of such ports specified to jlinker-init (or jstart-connection-pool if the connection-pool argument to jlinker-init is :delayed). A larger number will never be available.

The function returns two values:

The first is t if the specified state has been reached, or nil.

The second value describes the state of the connection pool:

• nil if there is no connection pool.
• :initializing if the pool is still under construction.
• an integer if the pool is ready with at least one port in each direction. The meaning of the integer depends on the other arguments to jquery-connection-pool (see just below).
• :terminated if jlinker-end is in progress.

When an integer is returned as the second value, its meaning depends on the values of the lisp-ports and java-ports arguments:

• If the lisp-ports and java-ports arguments are nil or omitted, an integer returned is the number of Lisp ports created to date.
• If only the lisp-ports argument is specified non-nil (and thus a positive integer less than or equal to the number of Lisp ports called for), wait until that many Lisp ports to Java are created and return the number of Lisp ports (or return the number of Lisp ports before that if wait is nil or a positive number).
• If only the java-ports argument is non-nil, wait until that many Java ports to Lisp are created; in this case, the second value is the number of Java ports to Lisp (or return the number of Java ports before that if wait is nil or a positive number).
• If both lisp-ports and java-ports are specified non-nil, wait until both numbers are reached (or return the number of Lisp ports before that if wait is nil or a positive number); in this case the second value is only the number of Lisp ports to Java.

Note that since the pool creation is taking place in parallel threads, whatever state results are returned may only be true for a moment.

See jlinker.htm for more information on the jLinker facility.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 9.0 release.
Created 2019.8.20.