Class Priority

Namespace

Temporalio.Api.Common.V1

Assembly

Temporalio.dll

Priority contains metadata that controls relative ordering of task processing when tasks are backed up in a queue. Initially, Priority will be used in matching (workflow and activity) task queues. Later it may be used in history task queues and in rate limiting decisions.

Priority is attached to workflows and activities. By default, activities inherit Priority from the workflow that created them, but may override fields when an activity is started or modified.

Despite being named "Priority", this message also contains fields that control "fairness" mechanisms.

For all fields, the field not present or equal to zero/empty string means to inherit the value from the calling workflow, or if there is no calling workflow, then use the default value.

For all fields other than fairness_key, the zero value isn't meaningful so there's no confusion between inherit/default and a meaningful value. For fairness_key, the empty string will be interpreted as "inherit". This means that if a workflow has a non-empty fairness key, you can't override the fairness key of its activity to the empty string.

The overall semantics of Priority are:

1. First, consider "priority": higher priority (lower number) goes first.
2. Then, consider fairness: try to dispatch tasks for different fairness keys in proportion to their weight.

Applications may use any subset of mechanisms that are useful to them and leave the other fields to use default values.

Not all queues in the system may support the "full" semantics of all priority fields. (Currently only support in matching task queues is planned.)

public sealed class Priority : IMessage<Priority>, IEquatable<Priority>, IDeepCloneable<Priority>, IBufferMessage, IMessage

Inheritance

object

Priority

Implements

IMessage<Priority>

IEquatable<Priority>

IDeepCloneable<Priority>

IBufferMessage

IMessage

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Constructors

Priority()

public Priority()

Priority(Priority)

public Priority(Priority other)

Parameters

other Priority

Fields

FairnessKeyFieldNumber

Field number for the "fairness_key" field.

public const int FairnessKeyFieldNumber = 2

Field Value

int

FairnessWeightFieldNumber

Field number for the "fairness_weight" field.

public const int FairnessWeightFieldNumber = 3

Field Value

int

PriorityKeyFieldNumber

Field number for the "priority_key" field.

public const int PriorityKeyFieldNumber = 1

Field Value

int

Properties

Descriptor

public static MessageDescriptor Descriptor { get; }

Property Value

MessageDescriptor

FairnessKey

Fairness key is a short string that's used as a key for a fairness balancing mechanism. It may correspond to a tenant id, or to a fixed string like "high" or "low". The default is the empty string.

The fairness mechanism attempts to dispatch tasks for a given key in proportion to its weight. For example, using a thousand distinct tenant ids, each with a weight of 1.0 (the default) will result in each tenant getting a roughly equal share of task dispatch throughput.

(Note: this does not imply equal share of worker capacity! Fairness decisions are made based on queue statistics, not current worker load.)

As another example, using keys "high" and "low" with weight 9.0 and 1.0 respectively will prefer dispatching "high" tasks over "low" tasks at a 9:1 ratio, while allowing either key to use all worker capacity if the other is not present.

All fairness mechanisms, including rate limits, are best-effort and probabilistic. The results may not match what a "perfect" algorithm with infinite resources would produce. The more unique keys are used, the less accurate the results will be.

Fairness keys are limited to 64 bytes.

public string FairnessKey { get; set; }

Property Value

string

FairnessWeight

Fairness weight for a task can come from multiple sources for flexibility. From highest to lowest precedence:

1. Weights for a small set of keys can be overridden in task queue configuration with an API.
2. It can be attached to the workflow/activity in this field.
3. The default weight of 1.0 will be used.

Weight values are clamped to the range [0.001, 1000].

public float FairnessWeight { get; set; }

Property Value

float

Parser

public static MessageParser<Priority> Parser { get; }

Property Value

MessageParser<Priority>

PriorityKey

Priority key is a positive integer from 1 to n, where smaller integers correspond to higher priorities (tasks run sooner). In general, tasks in a queue should be processed in close to priority order, although small deviations are possible.

The maximum priority value (minimum priority) is determined by server configuration, and defaults to 5.

If priority is not present (or zero), then the effective priority will be the default priority, which is is calculated by (min+max)/2. With the default max of 5, and min of 1, that comes out to 3.

public int PriorityKey { get; set; }

Property Value

int

Methods

CalculateSize()

Calculates the size of this message in Protocol Buffer wire format, in bytes.

public int CalculateSize()

Returns

int

The number of bytes required to write this message to a coded output stream.

Clone()

Creates a deep clone of this object.

public Priority Clone()

Returns

Priority

A deep clone of this object.

Equals(object)

Determines whether the specified object is equal to the current object.

public override bool Equals(object other)

Parameters

other object

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

Equals(Priority)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(Priority other)

Parameters

other Priority

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

MergeFrom(CodedInputStream)

Merges the data from the specified coded input stream with the current message.

public void MergeFrom(CodedInputStream input)

Parameters

input CodedInputStream

Remarks

See the user guide for precise merge semantics.

MergeFrom(Priority)

Merges the given message into this one.

public void MergeFrom(Priority other)

Parameters

other Priority

Remarks

See the user guide for precise merge semantics.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

WriteTo(CodedOutputStream)

Writes the data to the given coded output stream.

public void WriteTo(CodedOutputStream output)

Parameters

output CodedOutputStream

Coded output stream to write the data to. Must not be null.