Shared Resources
The Shared Resources Adding Build Features allows limiting the number of concurrently running builds using a shared resource, such as an external (to the CI server) resource, e.g. test database, or a server with a limited number of connections, etc.
Some of such resources may be accessed concurrently but allow only a limited number of connections, others require exclusive access. Adding different locks to shared resources addresses these cases: now you can define a resource on the project level, configure its parameters (e.g. type and quota) and then use this resource in specific build configurations by adding the Shared Resources build feature to them. The build starts once the lock on the resource is acquired; on the build completion the lock is released. While the builds using the resource are build state, the resource is unavailable, and the other builds requiring locks will be waiting in the build queue.
Adding and Editing Shared Resources
You can add, edit shared resources, and explore their details on the Shared Resources tab of the project configuration page. Shared resources defined at a project level will be available in all its subprojects and build configurations.
Types of Shared Resources
When you click Add new resource, three types of resources are available:
Infinite resource is a shared resource with an unlimited number of read locks.
Resource with quota: quota is a maximum number of read locks that can be acquired on the resource.
Resource with custom values: a custom value (e.g. a URL) is passed to the build that has acquired a lock on such a resource.
Using Shared Resources in Build Configurations
After shared resources have been created, you need to define which build configuration(s) will use them by adding this [build feature|Adding Build Features to the build configuration settings.
To define locks for the available resources, click Add lock. The following locks are available:
Locks for Resources with Quotas
For this resource type, two types of locks are supported:
Read locks - shared (multiple running builds with read locks are allowed).
Write locks - exclusive (only a single running build with a write lock is allowed).
A resource with a quota will allow concurrent access to multiple builds for reading but will restrict access to a single build for writes to the resource. Until all read locks are released, the build requiring a write lock will not start and will wait in the queue while new readers are able to acquire the lock. A build with a resource quota set to zero will not run.
Lock Fairness
While read locks enable multiple builds to concurrently access a shared resource with a quota > 1, lock fairness ensures that the build queue is not violated. It means, that if there is shared resource with a quota >1, and there are several queued builds with read locks and a build with a write lock in between the readers, the build with the write lock will wait until all builds with read locks earlier in the queue finish and release the lock. Then the build requiring a write lock will be executed, and only after that the other readers can acquire the lock. Lock fairness does not allow builds with read locks interfere with build queue ordering and 'slip' past the build that is waiting for a write lock to become available.
Locks for Resources with Custom Values
Resources with custom values support three types of locks:
Locks on any available value: a build that uses the resource will start if at least one of the values is available. If all values are being used at the moment, the build will wait in the queue.
Locks on all values: a build will lock all the values of the resource. No other builds that use this resource will start until the current one is finished.
Locks on specific value: only a specific value of the resource will be passed to the build. If the value is already taken by a running build, the new build will wait in the build Queue until the value becomes available.
When the resource is defined and the locks are added, the build gets a configuration parameter with the name of the lock and with the value of the resource string (teamcity.locks.readLock.<lockName> or teamcity.locks.writeLock.<lockName>), e.g. the parameter name can be: teamcity.locks.readLock.databaseUrl.
Development Links
See the Shared Resources plugin page at TeamCity Shared Resources.
JetBrains TV TeamCity Shared Resources Screencast