How to throttle matrix configurations in Jenkins declarative pipeline

Question

I need to throttle Matrix configurations in Jenkins declarative pipeline. For now I have a simple matrix like that:

    matrix {
      axes {
        axis {
          name 'Test'
          values 'Example1','Example2','Example3'
        }
      }
    }

And I can run only five configuration in parallel. First of all I created a category:

And now I'm trying to use throttle job property and there I'm stuck. As I see here in order to use throttle matrix configurations we need to pass matrixOptions parameters that contains two properties throttleMatrixBuilds and throttleMatrixConfigurations.

    options {
           throttleJobProperty(
           categories: ['ForTestMatrix'],
           throttleEnabled: true,
           throttleOption: 'category',
           matrixOptions: ???
           )
    }

Could someone tell me how to pass an object with two properties as a parameter there?

UPD I managed to run this code like that:

    options {
           throttleJobProperty(
           categories: ['ForTestMatrix'],
           throttleEnabled: true,
           throttleOption: 'category',
           matrixOptions: new hudson.plugins.throttleconcurrents.ThrottleMatrixProjectOptions(false, true)
           )
    }

But when I start this job I see in blue ocean that all the matrix configurations start at once. Does anyone have ideas why throttling doesn't work correctly?

Answer 1

See Throttle Concurrent Builds:

Unsupported use cases

This section contains links to the use cases which are not supported.

Throttling of code blocks without a node() definition

...

Throttling Pipeline via job properties

Starting in throttle-concurrents-2.0, using this option is not recommended. Use the throttle() step instead.

The following pipeline:

pipeline {
    
    agent any

    stages {
        stage('Matrix') {
            matrix {
                axes {
                    axis {
                        name 'Example'
                        values 'Example 1','Example 2','Example 3'
                    }
                }
                stages {
                    stage('Test') {
                        steps {
                            throttle(['ForTestMatrix']) {
                                node( 'master' ) {
                                    sh 'set +x; date; sleep 5; date'
                                }
                            } // throttle
                        } // steps
                    } // stage 'Test'
                } // stages
            } // matrix
        } // stage 'Matrix'
    } // stages
} // pipeline

gives this output:

                                 ...
[Matrix - Example = 'Example 1'] + set +x
                                 Fri Oct 22 15:54:01 GMT 2021
                                 Fri Oct 22 15:54:06 GMT 2021
                                 ...
[Matrix - Example = 'Example 2'] + set +x
                                 Fri Oct 22 15:54:06 GMT 2021
                                 Fri Oct 22 15:54:12 GMT 2021
                                 ...
[Matrix - Example = 'Example 3'] + set +x
                                 Fri Oct 22 15:54:12 GMT 2021
                                 Fri Oct 22 15:54:17 GMT 2021
                                 ...