RESOURCE_GROUPS

New in version 3.16.

Specify resources required by a test, grouped in a way that is meaningful to the test. See resource allocation for more information on how this property integrates into the CTest resource allocation feature.

The RESOURCE_GROUPS property is a semicolon-separated list of group descriptions. Each entry consists of an optional number of groups using the description followed by a series of resource requirements for those groups. These requirements (and the number of groups) are separated by commas. The resource requirements consist of the name of a resource type, followed by a colon, followed by an unsigned integer specifying the number of slots required on one resource of the given type.

The RESOURCE_GROUPS property tells CTest what resources a test expects to use grouped in a way meaningful to the test. The test itself must read the environment variables to determine which resources have been allocated to each group. For example, each group may correspond to a process the test will spawn when executed.

Consider the following example:

add_test(NAME MyTest COMMAND MyExe)
set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
  "2,gpus:2"
  "gpus:4,crypto_chips:2")

In this example, there are two group descriptions (implicitly separated by a semicolon.) The content of the first description is 2,gpus:2. This description specifies 2 groups, each of which requires 2 slots from a single GPU. The content of the second description is gpus:4,crypto_chips:2. This description does not specify a group count, so a default of 1 is assumed. This single group requires 4 slots from a single GPU and 2 slots from a single cryptography chip. In total, 3 resource groups are specified for this test, each with its own unique requirements.

Note that the number of slots following the resource type specifies slots from a single instance of the resource. If the resource group can tolerate receiving slots from different instances of the same resource, it can indicate this by splitting the specification into multiple requirements of one slot. For example:

add_test(NAME MyTest COMMAND MyExe)
set_property(TEST MyTest PROPERTY RESOURCE_GROUPS
  "gpus:1,gpus:1,gpus:1,gpus:1")

In this case, the single resource group indicates that it needs four GPU slots, all of which may come from separate GPUs (though they don't have to; CTest may still assign slots from the same GPU.)

When CTest sets the environment variables for a test, it assigns a group number based on the group description, starting at 0 on the left and the number of groups minus 1 on the right. For example, in the example above, the two groups in the first description would have IDs of 0 and 1, and the single group in the second description would have an ID of 2.

Both the RESOURCE_GROUPS and RESOURCE_LOCK properties serve similar purposes, but they are distinct and orthogonal. Resources specified by RESOURCE_GROUPS do not affect RESOURCE_LOCK, and vice versa. Whereas RESOURCE_LOCK is a simpler property that is used for locking one global resource, RESOURCE_GROUPS is a more advanced property that allows multiple tests to simultaneously use multiple resources of the same type, specifying their requirements in a fine-grained manner.