package flextape.proto

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc Allocate (AllocateRequest, AllocateResponse)

  flextape.proto:40

  Allocate attempts to allocate a specific license type for this invocation. If successful, invocations will keep the allocation alive by calling Refresh(). If the invocation is queued for the license instead, invocations will continue polling with Allocate() until allocation is successful. Returns: * NOT_FOUND if the license type is not known to the server * INVALID_ARGUMENT if the request is malformed (see request type for details)

  message AllocateRequest

  flextape.proto:65

  • optional Invocation invocation = 1

    Invocation details for this allocation

    required

  message AllocateResponse

  flextape.proto:70

  • oneof response_type

    • LicenseAllocated license_allocated = 1

      Returned when allocation is successful; the invocation should be able to proceed while simultaneously calling Refresh().

    • Queued queued = 2

      Returned when allocation is unsuccessful due to license contention. The invocation should continue to poll by calling Allocate() passing the invocation_id returned in this message.

• rpc LicensesStatus (LicensesStatusRequest, LicensesStatusResponse)

  flextape.proto:62

  LicensesStatus returns the status of all license types, as reported by both the Flextape and the underlying license servers.

  message LicensesStatusRequest

  flextape.proto:142

  Empty request

  (message has no fields)

  message LicensesStatusResponse

  flextape.proto:146

  • repeated LicenseStats license_stats = 1

    Stats for each managed license vendor/feature combination.

• rpc Refresh (RefreshRequest, RefreshResponse)

  flextape.proto:49

  Refresh refreshes a license allocation while an invocation is still potentially using the license. If the invocation fails to refresh the allocation, the underlying license may be allocated to another invocation. Returns: * NOT_FOUND if allocation is not known to the server, and the client should kill the invocation.

  message RefreshRequest

  flextape.proto:117

  • optional Invocation invocation = 1

    Existing invocation to refresh. Must have been allocated by a call to Allocate() successfully (not queued). Must have invocation_id set.

    required

  message RefreshResponse

  flextape.proto:124

  • string invocation_id = 1

    AllocateResponse that allocated this license.

  • optional google.protobuf.Timestamp license_refresh_deadline = 3

    Time at which the request license will be revoked. The client should issue another RefreshRequest for this invocation_id before this time.

• rpc Release (ReleaseRequest, ReleaseResponse)

  flextape.proto:58

  Release returns an allocated license to the pool. This should be called by clients to return licenses so they can be quickly allocated to other processes in the pool; otherwise, the server will need to wait for the client to time out issuing Refresh calls. Returns: * NOT_FOUND if the allocation is not known to the server.

  message ReleaseRequest

  flextape.proto:133

  • string invocation_id = 1

    AllocateResponse that allocated this license.

  message ReleaseResponse

  flextape.proto:138

  Empty response

  (message has no fields)

Message used for server config file

• repeated LicenseConfig license_configs = 1

  One LicenseConfig for each vendor::feature tuple. This should be configured from the license file the vendor provides.

• optional ServerConfig server = 2

Allocates licenses so that they are spread evenly across users. This means that users can jump ahead of the line, or be bumped after new requests.

Used in: LicenseConfig

(message has no fields)

Default prioritizer. Licenses are allocated in the order they are requested.

Used in: LicenseConfig

(message has no fields)

Used in: AllocateRequest, LicenseStats, RefreshRequest

• repeated License licenses = 1

  Licenses to acquire for this invocation. Invocations that need multiple of the same license type should insert duplicate entries in this field. Implementations currently only support reserving once license per invocation, though future implementations may allow for allocations of multiple and of different types.

  required

• string owner = 2

  Owning entity issuing the allocation request. Used for logging purposes only. This could be the name of the user or system issuing the request. This must be sent on every Allocate() and Refresh() call in case the server is restarted.

  required

• string build_tag = 3

  Build tag of the allocation request. This tag does not need to be unique across multiple AllocateRequests, and may be used to associate multiple such requests with one higher-level task. Typically the Bazel build invocation ID is used here. This must be sent on every Allocate() and Refresh() call in case the server is restarted.

  required

• string id = 4

  The server-generated ID for this invocation. In the initial Allocate() call, this can be blank for the initial request (to receive a generated one in the response) but subsequent Allocate() calls to refresh a queue position or Refresh() calls should have this field set.

Used in: Invocation, LicenseConfig, LicenseStats

• string vendor = 1

  Lower-case vendor name, such as `xilinx` or `cadence`.

  required

• string feature = 2

  Case-sensitive feature that this license is for, such as `Vivado_System_Edition` or `HLS`. These are defined by the underlying license server.

  required

Used in: AllocateResponse

• string invocation_id = 1

  Opaque identifier for this invocation, determined by the server. This ID should be used by the client in subsequent RefreshRequests for this license.

• optional google.protobuf.Timestamp license_refresh_deadline = 2

  Time at which the request license will be revoked. The client should issue a RefreshRequest for this invocation_id before this time.

Used in: Config

• optional License license = 1

  vendor::feature tuple

• uint32 quantity = 2

  Total number of licenses that can be allocated.

• oneof prioritizer

  Strategy to distribute licenses.

  • FIFOPrioritizer fifo = 3

  • EvenOwnersPrioritizer even_owners = 4

Used in: LicensesStatusResponse

• optional License license = 1

  License to which these stats apply.

• optional google.protobuf.Timestamp timestamp = 2

  Time at which these stats were accurate. Slightly stale stats may be returned due to the underlying polling interval, and stats are not an indication of whether a subsequent AllocateRequest will immediately result in an allocation.

• uint32 total_license_count = 3

  Number of licenses available in total, as reported by the underlying license server.

• uint32 allocated_count = 5

  Number of licenses currently allocated, as reported by the Flextape. This should be less than or equal to in_use_count.

• repeated Invocation allocated_invocations = 7

  Invocations that are currently allocated this license. These Invocation messages will not have the `licenses` field set - it is implied from being contained by this `LicenseStats`. This field is not inherently ordered.

• uint32 queued_count = 6

  Number of invocations queued for a license, as reported by the Flextape. If this number is >0, then allocated_count should equal total_license_count.

• repeated Invocation queued_invocations = 8

  Invocations that are currently queued for this license. These Invocation messages will not have the `licenses` field set - it is implied from being contained by this `LicenseStats`. This field ordered from next invocation to be allocated to last invocation to be allocated.

Used in: AllocateResponse

• string invocation_id = 1

  Opaque identifier for this invocation, determined by the server. This ID associates the invocation with a specific spot in the queue; it should be used in subsequent AllocateRequest messages or the invocation will be placed at the back of the queue.

• uint32 queue_position = 3

  Location of this invocation in the queue. Invocations in position 1 are next to be allocated, with higher positions getting allocations later than lower positions. The queue_position can increase or decrease over time depending on the license prioritization strategy configured, which may allow users to jump ahead of the line, or be bumped to the end of the line.

• optional google.protobuf.Timestamp next_poll_time = 2

  Time at which client should issue its next AllocateRequest. The client should issue its next poll after this time; if it fails to poll for significantly longer (>5s) it may be moved to the back of the queue.

General options for the entire instance

Used in: Config

• uint32 queue_refresh_duration_seconds = 1

  Interval on which actions should refresh their queue position while in queue for an allocation. Default: 15s

• uint32 allocation_refresh_duration_seconds = 2

  Interval on which actions should refresh their allocation while the action is executing. Default: 30s

• uint32 janitor_interval_seconds = 3

  Interval on which to clean up expired/released allocations and queue entries, and promote queued entries to allocations. Default: 1s

• uint32 adoption_duration_seconds = 4

  When the service first starts, for this period of time it holds off on allocating any new licenses, and instead listens for and "adopts" allocations that it hears about via the "Refresh" RPC. This duration should be >= allocation_refresh_duration_seconds, to guarantee that all clients Refresh() their allocation before the server moves into the normal operating state. Default: 45s