IDs, groups & names

Task IDs

Every task spawned within a pool receives an ID, which is an integer greater or equal to 0 that is unique within that task pool instance. An internal counter is incremented whenever a new task is spawned. A task with ID n was the (n+1)-th task to be spawned in the pool. Task IDs can be used to cancel specific tasks using the .cancel() method.

In practice, it should rarely be necessary to target specific tasks. When dealing with a regular TaskPool instance, you would typically cancel entire task groups (see below) rather than individual tasks, whereas with SimpleTaskPool instances you would indiscriminately cancel a number of tasks using the .stop() method.

The ID of a pool task also appears in the task’s name, which is set upon spawning it. (See here for the associated method of the Task class.)

Task groups

Every method of spawning new tasks in a task pool will add them to a task group and return the name of that group. With TaskPool methods such as .apply() and .map(), the group name can be set explicitly via the group_name parameter. By default, the name will be a string containing some meta information depending on which method is used. Passing an existing task group name in any of those methods will result in a InvalidGroupName error.

You can cancel entire task groups using the .cancel_group() method by passing it the group name. To check which tasks belong to a group, the .get_group_ids() method can be used, which takes group names and returns the IDs of the tasks belonging to them.

The SimpleTaskPool.start() method will create a new group as well, each time it is called, but it does not allow customizing the group name. Typically, it will not be necessary to keep track of groups in a SimpleTaskPool instance.

Task groups do not impose limits on the number of tasks in them, although they can be indirectly constrained by pool size limits.

Pool names

When initializing a task pool, you can provide a custom name for it, which will appear in its string representation, e.g. when using it in a print(). A class attribute keeps track of initialized task pools and assigns each one an index (similar to IDs for pool tasks). If no name is specified when creating a new pool, its index is used in the string representation of it. Pool names can be helpful when using multiple pools and analyzing log messages.