Note: this component has a complexity level of "expert", which means that objects of this type are not expected to be created or altered. Please contact UnboundID support for assistance if you believe that you have a need to create or modify this type of object.
The UnboundID Work Queue may be used to ensure that operations requested of the server are processed in a timely manner. It maintains multiple blocking queues which are serviced by separate sets of worker threads to avoid too much contention around a single blocking queue.
↓Parent Component
↓Properties
↓dsconfig Usage
The UnboundID Work Queue component inherits from the Work Queue
The properties supported by this managed object are as follows:
| Description | Specifies the total number of worker threads that should be used within the server in order to process requested operations. The worker threads will be split evenly across all of the configured queues. If a nonzero value is configured, then that number of worker threads will be used (although the actual number may be increased as needed to make it possible to have an even number across all queues). A value of zero indicates that the Metrics Engine will attempt to automatically select an optimal value (for systems with fewer than 16 CPUs then a value of 16 will be selected; for larger systems the number of worker threads selected will be equal to the number of available CPUs). |
| Default Value | 0 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Metrics Engine must be restarted for changes to this setting to take effect. This modification requires that you manually restart the server for the change to take effect |
| Description | Specifies the number of blocking queues that should be maintained. A value of zero indicates that the server should attempt to automatically select an optimal value (one queue for every eight worker threads). |
| Default Value | 0 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Metrics Engine must be restarted for changes to this setting to take effect. This modification requires that you manually restart the server for the change to take effect |
| Description | Specifies the maximum number of pending operations that may be held in any of the queues at any given time. The total number of pending requests may be as large as this value times the total number of queues. A value of zero indicates that the capacity of the work queue is not limited. If a nonzero value is configured and a queue is already at its maximum capacity, then attempts to add new operations to the queue will be rejected. |
| Default Value | 1000 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Metrics Engine must be restarted for changes to this setting to take effect. This modification requires that you manually restart the server for the change to take effect |
| Description | Specifies the maximum length of time that the connection handler should be allowed to wait to enqueue a request if the work queue is full. If the attempt to enqueue an operation does not succeed within this period of time, then the operation will be rejected and an error response will be returned to the client. A value of zero indicates that operations should be rejected immediately if the work queue is already at its maximum capacity. |
| Default Value | 60 seconds |
| Allowed Values | A duration. Lower limit is 0 milliseconds. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Indicates whether the work queue should monitor the length of time that operations are held in the queue. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the maximum length of time that an operation should be allowed to wait on the work queue. If an operation has been waiting on the queue longer than this period of time, then it will receive an immediate failure result rather than being processed once it has been handed off to a worker thread. A value of zero seconds indicates that there should not be any maximum queue time imposed. This setting will only be used if the monitor-queue-time property has a value of true. |
| Default Value | 0 seconds |
| Allowed Values | A duration. Lower limit is 0 milliseconds. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
include-operation-details-in-worker-thread-name
| Description | Indicates whether the names of the worker threads should be dynamically updated to reflect the operation that they are currently processing. If this is true, then the name of the worker thread will be updated to include the connection ID and operation ID of the operation that it is currently processing. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
num-write-worker-threads (Advanced Property)
| Description | Specifies the number of worker threads that should be used within the server to process write (add, delete, modify, and modify DN) operations. If this is specified, then separate sets of worker threads will be used for processing read and write operations, and the value of the num-worker-threads property will reflect the number of threads to use to process read operations. |
| Default Value | Read and write operations will be processed by the same worker threads rather than having separate sets of worker threads for read operations than for write operations. |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Metrics Engine must be restarted for changes to this setting to take effect. This modification requires that you manually restart the server for the change to take effect |
num-administrative-session-worker-threads (Advanced Property)
| Description | Specifies the number of worker threads that should be used to process operations as part of an administrative session. These threads may be reserved only for special use by management applications like dsconfig, the administration console, and other administrative tools, so that these applications may be used to diagnose problems and take any necessary corrective action even if all "normal" worker threads are busy processing other requests. If a nonzero value is configured for this property, then that number of threads will be configured and used to process operations on connections with an active administrative session (created using the start administrative session extended operation, and lasting until an end administrative session request is received, or the connection is closed). Assuming that one or more administrative session worker threads are allocated, then the start administrative operation extended request will always be processed using one of these threads. If that request indicates that this thread pool should be used, then subsequent StartTLS and bind requests on that connection will also be processed using a worker thread from this dedicated pool. All other operations on a connection with an active administrative session will only be processed in the dedicated thread pool if the connection is authenticated as a user with the use-admin-session privilege. A value of zero indicates that there should not be any dedicated threads for administrative sessions, and that the same pool of worker threads will be used for both "normal" and administrative operations. |
| Default Value | 8 |
| Allowed Values | An integer value. Lower limit is 0. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Metrics Engine must be restarted for changes to this setting to take effect. This modification requires that you manually restart the server for the change to take effect |
num-write-queues (Advanced Property)
| Description | Specifies the number of blocking queues that should be maintained for write operations. This will only be used if a value is specified for the num-write-worker-threads property, in which case the num-queues property will specify the number of queues for read operations. Otherwise, all operations will be processed by a common set of worker threads and the value of the num-queues property will specify the number of queues for all types of operations. |
| Default Value | 1 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Metrics Engine must be restarted for changes to this setting to take effect. This modification requires that you manually restart the server for the change to take effect |
expensive-operation-check-interval (Advanced Property)
| Description | The interval that the work queue should use when checking for potentially expensive operations. If at least expensive-operation-minimum-concurrent-count worker threads are found to be processing the same operation on two consecutive polls separated by this time interval (i.e., the worker thread has been processing that operation for at least this length of time, and potentially up to twice this length of time), then a stack trace of all running threads will be written to a file for analysis to provide potentially useful information that may help better understand the reason it is taking so long. It may be that the operation is simply an expensive one to process, but there may be other external factors (e.g., a database checkpoint, a log rotation, lock contention, etc.) that could be to blame. This option is primarily intended for debugging purposes and should generally be used under the direction of UnboundID support. |
| Default Value | Expensive operation monitoring will not be enabled. |
| Allowed Values | A duration. Lower limit is 0 milliseconds. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
expensive-operation-minimum-concurrent-count (Advanced Property)
| Description | The minimum number of concurrent expensive operations that should be detected to trigger dumping stack traces for all threads. If at least this number of worker threads are seen processing the same operations in two consecutive intervals, then the server will dump a stack trace of all threads to a file. This option is primarily intended for debugging purposes and should generally be used under the direction of UnboundID support. |
| Default Value | 1 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
expensive-operation-minimum-dump-interval (Advanced Property)
| Description | The minimum length of time that should be required to pass after dumping stack trace information for all threads before the server should be allowed to create a second dump. This will help prevent the server from dumping stack traces too frequently and eventually consuming all available disk space with stack trace log output. This option is primarily intended for debugging purposes and should generally be used under the direction of UnboundID support. |
| Default Value | 60 seconds |
| Allowed Values | A duration. Lower limit is 0 milliseconds. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
queue-type (Advanced Property)
| Description | Specifies the type of Java queue that should be used to provide the associated functionality. Note that the choice of queue implementation may have an impact on how the max-work-queue-capacity property will be handled. |
| Default Value | If the configured capacity is between 1 and 100000 (inclusive), then a non-fair array blocking queue will be used. Otherwise, a linked blocking queue will be used. |
| Allowed Values | linked-blocking-queue - Indicates that the java.util.concurrent.LinkedBlockingQueue implementation should be used. The max-work-queue-capacity property may have any value greater than or equal to zero, and if a nonzero value is provided, then that maximum capacity will be enforced. fair-array-blocking-queue - Indicates that the java.util.concurrent.ArrayBlockingQueue implementation should be used with a fair ordering policy. The max-work-queue-capacity property must be defined with a value greater than zero, and that maximum capacity will be enforced. non-fair-array-blocking-queue - Indicates that the java.util.concurrent.ArrayBlockingQueue implementation should be used with a non-fair ordering policy. The max-work-queue-capacity property must be defined with a value greater than zero, and that maximum capacity will be enforced. fair-synchronous-queue - Indicates that the java.util.concurrent.SynchronousQueue implementation should be used with a fair ordering policy. The value of the max-work-queue-capacity property will not be used in any way. Also note that because synchronous queues do not have any capacity, the current, maximum, and average work queue sizes will always be zero in the work queue monitor entry. non-fair-synchronous-queue - Indicates that the java.util.concurrent.SynchronousQueue implementation should be used with a non-fair ordering policy. The value of the max-work-queue-capacity property will not be used in any way. Also note that because synchronous queues do not have any capacity, the current, maximum, and average work queue sizes will always be zero in the work queue monitor entry. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Metrics Engine must be restarted for changes to this setting to take effect. This modification requires that you manually restart the server for the change to take effect |
To view the Work Queue configuration:
dsconfig get-work-queue-prop
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the Work Queue configuration:
dsconfig set-work-queue-prop
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...