Page MenuHomePhabricator
Diviner Phabricator Tech Docs DrydockBlueprintImplementation

abstract class DrydockBlueprintImplementation
Phabricator Technical Documentation (Drydock)

This class is not documented.

Tasks

Lease Acquisition

  • abstract public function canAcquireLeaseOnResource($blueprint, $resource, $lease) — Enforce basic checks on lease/resource compatibility. Allows resources to reject leases if they are incompatible, even if the resource types match.
  • abstract public function acquireLease($blueprint, $resource, $lease) — Acquire a lease. Allows resources to perform setup as leases are brought online.
  • public function activateLease($blueprint, $resource, $lease)
  • abstract public function didReleaseLease($blueprint, $resource, $lease) — React to a lease being released.
  • abstract public function destroyLease($blueprint, $resource, $lease) — Destroy any temporary data associated with a lease.
  • public function shouldAllocateSupplementalResource($blueprint, $resource, $lease) — Return true to try to allocate a new resource and expand the resource pool instead of permitting an otherwise valid acquisition on an existing resource.

Resource Allocation

  • abstract public function canAnyBlueprintEverAllocateResourceForLease($lease) — Enforce fundamental implementation/lease checks. Allows implementations to reject a lease which no concrete blueprint can ever satisfy.
  • abstract public function canEverAllocateResourceForLease($blueprint, $lease) — Enforce basic blueprint/lease checks. Allows blueprints to reject a lease which they can not build a resource for.
  • abstract public function canAllocateResourceForLease($blueprint, $lease) — Enforce basic availability limits. Allows blueprints to reject resource allocation if they are currently overallocated.
  • abstract public function allocateResource($blueprint, $lease) — Allocate a suitable resource for a lease.
  • public function activateResource($blueprint, $resource)
  • abstract public function destroyResource($blueprint, $resource) — Destroy any temporary data associated with a resource.
  • abstract public function getResourceName($blueprint, $resource) — Get a human readable name for a resource.

Resource Interfaces

No methods for this task.

Logging

No methods for this task.

Other Methods

Methods

abstract public function getType()

This method is not documented.
Return
wild

abstract public function isEnabled()

This method is not documented.
Return
wild

abstract public function getBlueprintName()

This method is not documented.
Return
wild

abstract public function getDescription()

This method is not documented.
Return
wild

public function getBlueprintIcon()

This method is not documented.
Return
wild

public function getFieldSpecifications()

This method is not documented.
Return
wild

protected function getCustomFieldSpecifications()

This method is not documented.
Return
wild

public function getViewer()

This method is not documented.
Return
wild

abstract public function canAcquireLeaseOnResource($blueprint, $resource, $lease)

Enforce basic checks on lease/resource compatibility. Allows resources to reject leases if they are incompatible, even if the resource types match.

For example, if a resource represents a 32-bit host, this method might reject leases that need a 64-bit host. The blueprint might also reject a resource if the lease needs 8GB of RAM and the resource only has 6GB free.

This method should not acquire locks or expect anything to be locked. This is a coarse compatibility check between a lease and a resource.

Parameters
DrydockBlueprint$blueprintConcrete blueprint to allocate for.
DrydockResource$resourceCandidate resource to allocate the lease on.
DrydockLease$leasePending lease that wants to allocate here.
Return
boolTrue if the resource and lease are compatible.

abstract public function acquireLease($blueprint, $resource, $lease)

Acquire a lease. Allows resources to perform setup as leases are brought online.

If acquisition fails, throw an exception.

Parameters
DrydockBlueprint$blueprintBlueprint which built the resource.
DrydockResource$resourceResource to acquire a lease on.
DrydockLease$leaseRequested lease.
Return
void

public function activateLease($blueprint, $resource, $lease)

This method is not documented.
Parameters
DrydockBlueprint$blueprint
DrydockResource$resource
DrydockLease$lease
Return
void

abstract public function didReleaseLease($blueprint, $resource, $lease)

React to a lease being released.

This callback is primarily useful for automatically releasing resources once all leases are released.

Parameters
DrydockBlueprint$blueprintBlueprint which built the resource.
DrydockResource$resourceResource a lease was released on.
DrydockLease$leaseRecently released lease.
Return
void

abstract public function destroyLease($blueprint, $resource, $lease)

Destroy any temporary data associated with a lease.

If a lease creates temporary state while held, destroy it here.

Parameters
DrydockBlueprint$blueprintBlueprint which built the resource.
DrydockResource$resourceResource the lease is acquired on.
DrydockLease$leaseThe lease being destroyed.
Return
void

public function shouldAllocateSupplementalResource($blueprint, $resource, $lease)

Return true to try to allocate a new resource and expand the resource pool instead of permitting an otherwise valid acquisition on an existing resource.

This allows the blueprint to provide a soft hint about when the resource pool should grow.

Returning "true" in all cases generally makes sense when a blueprint controls a fixed pool of resources, like a particular number of physical hosts: you want to put all the hosts in service, so whenever it is possible to allocate a new host you want to do this.

Returning "false" in all cases generally make sense when a blueprint has a flexible pool of expensive resources and you want to pack leases onto them as tightly as possible.

Parameters
DrydockBlueprint$blueprintThe blueprint for an existing resource being acquired.
DrydockResource$resourceThe resource being acquired, which we may want to build a supplemental resource for.
DrydockLease$leaseThe current lease performing acquisition.
Return
boolTrue to prefer allocating a supplemental resource.

abstract public function canAnyBlueprintEverAllocateResourceForLease($lease)

Enforce fundamental implementation/lease checks. Allows implementations to reject a lease which no concrete blueprint can ever satisfy.

For example, if a lease only builds ARM hosts and the lease needs a PowerPC host, it may be rejected here.

This is the earliest rejection phase, and followed by canEverAllocateResourceForLease().

This method should not actually check if a resource can be allocated right now, or even if a blueprint which can allocate a suitable resource really exists, only if some blueprint may conceivably exist which could plausibly be able to build a suitable resource.

Parameters
DrydockLease$leaseRequested lease.
Return
boolTrue if some concrete blueprint of this implementation's type might ever be able to build a resource for the lease.

abstract public function canEverAllocateResourceForLease($blueprint, $lease)

Enforce basic blueprint/lease checks. Allows blueprints to reject a lease which they can not build a resource for.

This is the second rejection phase. It follows canAnyBlueprintEverAllocateResourceForLease() and is followed by canAllocateResourceForLease().

This method should not check if a resource can be built right now, only if the blueprint as configured may, at some time, be able to build a suitable resource.

Parameters
DrydockBlueprint$blueprintBlueprint which may be asked to allocate a resource.
DrydockLease$leaseRequested lease.
Return
boolTrue if this blueprint can eventually build a suitable resource for the lease, as currently configured.

abstract public function canAllocateResourceForLease($blueprint, $lease)

Enforce basic availability limits. Allows blueprints to reject resource allocation if they are currently overallocated.

This method should perform basic capacity/limit checks. For example, if it has a limit of 6 resources and currently has 6 resources allocated, it might reject new leases.

This method should not acquire locks or expect locks to be acquired. This is a coarse check to determine if the operation is likely to succeed right now without needing to acquire locks.

It is expected that this method will sometimes return true (indicating that a resource can be allocated) but find that another allocator has eaten up free capacity by the time it actually tries to build a resource. This is normal and the allocator will recover from it.

Parameters
DrydockBlueprint$blueprintThe blueprint which may be asked to allocate a resource.
DrydockLease$leaseRequested lease.
Return
boolTrue if this blueprint appears likely to be able to allocate a suitable resource.

abstract public function allocateResource($blueprint, $lease)

Allocate a suitable resource for a lease.

This method MUST acquire, hold, and manage locks to prevent multiple allocations from racing. World state is not locked before this method is called. Blueprints are entirely responsible for any lock handling they need to perform.

Parameters
DrydockBlueprint$blueprintThe blueprint which should allocate a resource.
DrydockLease$leaseRequested lease.
Return
DrydockResourceAllocated resource.

public function activateResource($blueprint, $resource)

This method is not documented.
Parameters
DrydockBlueprint$blueprint
DrydockResource$resource
Return
wild

abstract public function destroyResource($blueprint, $resource)

Destroy any temporary data associated with a resource.

If a resource creates temporary state when allocated, destroy that state here. For example, you might shut down a virtual host or destroy a working copy on disk.

Parameters
DrydockBlueprint$blueprintBlueprint which built the resource.
DrydockResource$resourceResource being destroyed.
Return
void

abstract public function getResourceName($blueprint, $resource)

Get a human readable name for a resource.

Parameters
DrydockBlueprint$blueprintBlueprint which built the resource.
DrydockResource$resourceResource to get the name of.
Return
stringHuman-readable resource name.

abstract public function getInterface($blueprint, $resource, $lease, $type)

This method is not documented.
Parameters
DrydockBlueprint$blueprint
DrydockResource$resource
DrydockLease$lease
$type
Return
wild

public static function getAllBlueprintImplementations()

This method is not documented.
Return
wild

public static function getNamedImplementation($class)

This method is not documented.
Parameters
$class
Return
wild

protected function newResourceTemplate($blueprint)

This method is not documented.
Parameters
DrydockBlueprint$blueprint
Return
wild

protected function newLease($blueprint)

This method is not documented.
Parameters
DrydockBlueprint$blueprint
Return
wild

protected function requireActiveLease($lease)

This method is not documented.
Parameters
DrydockLease$lease
Return
wild

protected function shouldUseConcurrentResourceLimit()

Does this implementation use concurrent resource limits?

Implementations can override this method to opt into standard limit behavior, which provides a simple concurrent resource limit.

Return
boolTrue to use limits.

protected function getConcurrentResourceLimit($blueprint)

Get the effective concurrent resource limit for this blueprint.

Parameters
DrydockBlueprint$blueprintBlueprint to get the limit for.
Return
int|nullLimit, or `null` for no limit.

protected function getConcurrentResourceLimitSlotLock($blueprint)

This method is not documented.
Parameters
DrydockBlueprint$blueprint
Return
wild

protected function shouldLimitAllocatingPoolSize($blueprint)

Apply standard limits on resource allocation rate.

Parameters
DrydockBlueprint$blueprintThe blueprint requesting an allocation.
Return
boolTrue if further allocations should be limited.
Defined
src/applications/drydock/blueprint/DrydockBlueprintImplementation.php:9
Phabricator · Built by Phacility