#244

Committed 10 Apr 2024 08:19PM UTC coverage: 77.465% (-0.08%) from 77.549%

Build # #244

Build Type

push

github

Committed by

web-flow

Commit Message

Slot supplier interface & fixed-size implementation (#2014)

https://github.com/temporalio/proposals/blob/master/all-sdk/autotuning.md

Run Details

286 of 388 new or added lines in 25 files covered. (73.71%)

3 existing lines in 3 files now uncovered.

19116 of 24677 relevant lines covered (77.46%)

0.77 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/temporal-sdk/src/main/java/io/temporal/worker/tuning/SlotSupplier.java

/*
 * Copyright (C) 2022 Temporal Technologies, Inc. All Rights Reserved.
 *
 * Copyright (C) 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 *
 * Modifications copyright (C) 2017 Uber Technologies, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this material except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.temporal.worker.tuning;

import io.temporal.common.Experimental;
import java.util.Optional;

/**
 * A SlotSupplier is responsible for managing the number of slots available for a given type of
 * task. The three types of tasks are workflow, activity, and local activity. Implementing this
 * interface allows you to carefully control how many tasks of any given type a worker will process
 * at once.
 *
 * @param <SI> The type of information that will be used to reserve a slot. The three info types are
 *     {@link WorkflowSlotInfo}, {@link ActivitySlotInfo}, and {@link LocalActivitySlotInfo}.
 */
@Experimental
public interface SlotSupplier<SI extends SlotInfo> {
  /**
   * This function is called before polling for new tasks. Your implementation should block until a
   * slot is available, then return a permit to use that slot.
   *
   * @param ctx The context for slot reservation.
   * @return A permit to use the slot which may be populated with your own data.
   * @throws InterruptedException The worker may choose to interrupt the thread in order to cancel
   *     the reservation, or during shutdown. You may perform cleanup, and then should rethrow the
   *     exception.
   */
  SlotPermit reserveSlot(SlotReserveContext<SI> ctx) throws InterruptedException;

  /**
   * This function is called when trying to reserve slots for "eager" workflow and activity tasks.
   * Eager tasks are those which are returned as a result of completing a workflow task, rather than
   * from polling. Your implementation must not block, and If a slot is available, return a permit
   * to use that slot.
   *
   * @param ctx The context for slot reservation.
   * @return Maybe a permit to use the slot which may be populated with your own data.
   */
  Optional<SlotPermit> tryReserveSlot(SlotReserveContext<SI> ctx);

  /**
   * This function is called once a slot is actually being used to process some task, which may be
   * some time after the slot was reserved originally. For example, if there is no work for a
   * worker, a number of slots equal to the number of active pollers may already be reserved, but
   * none of them are being used yet. This call should be non-blocking.
   *
   * @param ctx The context for marking a slot as used.
   */
  void markSlotUsed(SlotMarkUsedContext<SI> ctx);

  /**
   * This function is called once a permit is no longer needed. This could be because the task has
   * finished, whether successfully or not, or because the slot was no longer needed (ex: the number
   * of active pollers decreased). This call should be non-blocking.
   *
   * @param ctx The context for releasing a slot.
   */
  void releaseSlot(SlotReleaseContext<SI> ctx);

  /**
   * Because we currently use thread pools to execute tasks, there must be *some* defined
   * upper-limit on the size of the thread pool for each kind of task. You must not hand out more
   * permits than this number. If unspecified, the default is {@link Integer#MAX_VALUE}. Be aware
   * that if your implementation hands out unreasonable numbers of permits, you could easily
   * oversubscribe the worker, and cause it to run out of resources.
   *
   * <p>This value should never change during the lifetime of the supplier.
   *
   * @return the maximum number of slots that can ever be in use at one type for this slot type.
   */
  default int getMaximumSlots() {
    return Integer.MAX_VALUE;
  }
}

1	/*
2	* Copyright (C) 2022 Temporal Technologies, Inc. All Rights Reserved.
3	*
4	* Copyright (C) 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
5	*
6	* Modifications copyright (C) 2017 Uber Technologies, Inc.
7	*
8	* Licensed under the Apache License, Version 2.0 (the "License");
9	* you may not use this material except in compliance with the License.
10	* You may obtain a copy of the License at
11	*
12	* http://www.apache.org/licenses/LICENSE-2.0
13	*
14	* Unless required by applicable law or agreed to in writing, software
15	* distributed under the License is distributed on an "AS IS" BASIS,
16	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17	* See the License for the specific language governing permissions and
18	* limitations under the License.
19	*/
20
21	package io.temporal.worker.tuning;
22
23	import io.temporal.common.Experimental;
24	import java.util.Optional;
25
26	/**
27	* A SlotSupplier is responsible for managing the number of slots available for a given type of
28	* task. The three types of tasks are workflow, activity, and local activity. Implementing this
29	* interface allows you to carefully control how many tasks of any given type a worker will process
30	* at once.
31	*
32	* @param <SI> The type of information that will be used to reserve a slot. The three info types are
33	* {@link WorkflowSlotInfo}, {@link ActivitySlotInfo}, and {@link LocalActivitySlotInfo}.
34	*/
35	@Experimental
36	public interface SlotSupplier<SI extends SlotInfo> {
37	/**
38	* This function is called before polling for new tasks. Your implementation should block until a
39	* slot is available, then return a permit to use that slot.
40	*
41	* @param ctx The context for slot reservation.
42	* @return A permit to use the slot which may be populated with your own data.
43	* @throws InterruptedException The worker may choose to interrupt the thread in order to cancel
44	* the reservation, or during shutdown. You may perform cleanup, and then should rethrow the
45	* exception.
46	*/
47	SlotPermit reserveSlot(SlotReserveContext<SI> ctx) throws InterruptedException;
48
49	/**
50	* This function is called when trying to reserve slots for "eager" workflow and activity tasks.
51	* Eager tasks are those which are returned as a result of completing a workflow task, rather than
52	* from polling. Your implementation must not block, and If a slot is available, return a permit
53	* to use that slot.
54	*
55	* @param ctx The context for slot reservation.
56	* @return Maybe a permit to use the slot which may be populated with your own data.
57	*/
58	Optional<SlotPermit> tryReserveSlot(SlotReserveContext<SI> ctx);
59
60	/**
61	* This function is called once a slot is actually being used to process some task, which may be
62	* some time after the slot was reserved originally. For example, if there is no work for a
63	* worker, a number of slots equal to the number of active pollers may already be reserved, but
64	* none of them are being used yet. This call should be non-blocking.
65	*
66	* @param ctx The context for marking a slot as used.
67	*/
68	void markSlotUsed(SlotMarkUsedContext<SI> ctx);
69
70	/**
71	* This function is called once a permit is no longer needed. This could be because the task has
72	* finished, whether successfully or not, or because the slot was no longer needed (ex: the number
73	* of active pollers decreased). This call should be non-blocking.
74	*
75	* @param ctx The context for releasing a slot.
76	*/
77	void releaseSlot(SlotReleaseContext<SI> ctx);
78
79	/**
80	* Because we currently use thread pools to execute tasks, there must be some defined
81	* upper-limit on the size of the thread pool for each kind of task. You must not hand out more
82	* permits than this number. If unspecified, the default is {@link Integer#MAX_VALUE}. Be aware
83	* that if your implementation hands out unreasonable numbers of permits, you could easily
84	* oversubscribe the worker, and cause it to run out of resources.
85	*
86	* <p>This value should never change during the lifetime of the supplier.
87	*
88	* @return the maximum number of slots that can ever be in use at one type for this slot type.
89	*/
90	default int getMaximumSlots() {
NEW 91	return Integer.MAX_VALUE;	×
92	}
93	}

temporalio / sdk-java / #244

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous