CountsAndLists: SDK Reference #3537
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Build Succeeded 👏 Build Id: 5410ef39-9ad6-4675-be6e-1244043c0cf1 The following development artifacts have been built, and will exist for the next 30 days:
A preview of the website (the last 30 builds are retained): To install this version:
|
igooch
reviewed
Dec 12, 2023
There was a problem hiding this comment.
Thanks for this -- it's a lot of SDK methods! This review is split over two different commits (I didn't see a quick way to move comments on the first commit to head on the PR). Most of the suggestions are minor things around consistency in formatting and return values. Let me know if you have any questions!
|
|
||
| ### Alpha().GetCounterCount(key) | ||
|
|
||
| This function retrieves the current count for a specified Counter in the game server. It ensures the count is accurate based on the predefined keys in the GameServer resource, and returns an error if the key is not predefined. |
There was a problem hiding this comment.
The count here behaves different than with Player Tracking. For Counters and Lists changes can be made via Game Server Allocation Actions in addition to through the SDK, so this Count may not always be accurate as it could be reading cached data. The count will be eventually consistent when coming back to the SDK. (This is noted in #2716 as a design trade off.)
There was a problem hiding this comment.
Included this info in the Note section.👍🏻
|
|
||
| ### Alpha().SetListCapacity(key, amount) | ||
|
|
||
| This function sets the capacity for a specified List, identified by its key (name), with the capacity value required to be between 0 and 1000. It returns an error if the key wasn't predefined in the GameServer resource. The function returns `true` if the capacity is successfully set, and an error if the operation fails. |
There was a problem hiding this comment.
Suggested change
| This function sets the capacity for a specified List, identified by its key (name), with the capacity value required to be between 0 and 1000. It returns an error if the key wasn't predefined in the GameServer resource. The function returns `true` if the capacity is successfully set, and an error if the operation fails. | |
| This function sets the capacity for a specified List, identified by its key (name), with the capacity value required to be between 0 and 1000. It returns an error if the key wasn't predefined in the GameServer resource. The function returns `true` if the capacity is successfully set, or `false` and an error if the operation fails. |
|
|
||
| ### Alpha().SetCounterCount(key, amount) | ||
|
|
||
| This function sets the count to a given value. This operation overwrites any previous values and the new value cannot exceed the Counter's capacity. The function returns `true` if successful, along with an `error` if the operation fails. |
There was a problem hiding this comment.
Suggested change
| This function sets the count to a given value. This operation overwrites any previous values and the new value cannot exceed the Counter's capacity. The function returns `true` if successful, along with an `error` if the operation fails. | |
| This function sets the count to a given value. This operation overwrites any previous values and the new value cannot exceed the Counter's capacity. The function returns `true` if successful, or `false` along with an `error` if the operation fails. |
|
|
||
| ### Alpha().IncrementCounter(key, amount) | ||
|
|
||
| This function increments the count of a specified Counter by a given nonnegative amount. It updates the current CRD value and maxes out at the maximum value of `int64`. The function returns an `error` if the key wasn't predefined in the GameServer resource and returns `false` if the Counter is already at capacity, indicating no increment will occur. There is a potential race condition when count values are set from both the SDK and through the K8s API(Allocation or otherwise), since the SDK append operation back to the CRD value is batched asynchronous any value incremented past the capacity will be silently truncated. |
There was a problem hiding this comment.
Suggested change
| This function increments the count of a specified Counter by a given nonnegative amount. It updates the current CRD value and maxes out at the maximum value of `int64`. The function returns an `error` if the key wasn't predefined in the GameServer resource and returns `false` if the Counter is already at capacity, indicating no increment will occur. There is a potential race condition when count values are set from both the SDK and through the K8s API(Allocation or otherwise), since the SDK append operation back to the CRD value is batched asynchronous any value incremented past the capacity will be silently truncated. | |
| This function increments the count of a specified Counter by a given nonnegative value amount. The function returns `false` and an `error` if the key wasn't predefined in the GameServer resource and returns or if the Counter is already at capacity, indicating no increment will occur. If the update is successful this returns `true`. | |
| There is a potential race condition when count values are set from both the SDK and through the K8s API(Allocation or otherwise), since the SDK update operation back to the CRD value is batched asynchronous any value incremented past the capacity will be silently truncated to capacity. |
|
|
||
| ### Alpha().GetCounterCount(key) | ||
|
|
||
| This function retrieves the current count for a specified Counter in the game server. It ensures the count is accurate based on the predefined keys in the GameServer resource, and returns an error if the key is not predefined. |
There was a problem hiding this comment.
Suggested change
| This function retrieves the current count for a specified Counter in the game server. It ensures the count is accurate based on the predefined keys in the GameServer resource, and returns an error if the key is not predefined. | |
| This function retrieves the current count for a specified Counter in the game server. This returns `-1` an `error` if the key is not predefined. |
|
|
||
| This function removes a string from a List's values using its key(name) and the specific string value. It returns an | ||
| `error` if the string does not exist in the list or if the key wasn't predefined in the GameServer resource. The function | ||
| returns `true` if the deletion is successful, and an error if it fails. |
There was a problem hiding this comment.
Suggested change
| returns `true` if the deletion is successful, and an error if it fails. | |
| returns `true` if the deletion is successful, or `false` and an `error` if it fails. |
|
|
||
| This function retrieves the capacity of a specified List using its key(name). It returns an error if the key wasn't | ||
| predefined in the GameServer resource. The function provides the List's capacity value if successful, or `-1` along with | ||
| an error in case of failure. |
There was a problem hiding this comment.
Suggested change
| an error in case of failure. | |
| an `error` in case of failure. |
|
|
||
| #### Alpha().GetListCapacity(key) | ||
|
|
||
| This function retrieves the capacity of a specified List using its key(name). It returns an error if the key wasn't |
There was a problem hiding this comment.
Suggested change
| This function retrieves the capacity of a specified List using its key(name). It returns an error if the key wasn't | |
| This function retrieves the capacity of a specified List using its key(name). It returns `-1` and an `error` if the key wasn't |
|
|
||
| This function checks if a specific string value exists in a List's values, identified by the List's key(name). | ||
| The search is case-sensitive. It returns `true` if the string is found in the list, and `false` otherwise. | ||
| An error is returned if the key wasn't predefined in the GameServer resource or if there's an issue in fetching the List. |
There was a problem hiding this comment.
Suggested change
| An error is returned if the key wasn't predefined in the GameServer resource or if there's an issue in fetching the List. | |
| `false` and an error are returned if the key wasn't predefined in the GameServer resource or if there's an issue in fetching the List. |
| #### Alpha().GetListLength(key) | ||
|
|
||
| This function retrieves the number of items (length) in the Values list of a specified List, identified by the List's key(name). | ||
| It returns the length of the list if successful, or `-1` along with an error in case of failure, such as if the key wasn't |
There was a problem hiding this comment.
Suggested change
| It returns the length of the list if successful, or `-1` along with an error in case of failure, such as if the key wasn't | |
| It returns the length of the list if successful, or `-1` along with an `error` in case of failure, such as if the key wasn't |
|
Build Succeeded 👏 Build Id: 507f3be6-94a0-4252-a6f0-c7609a50dfba The following development artifacts have been built, and will exist for the next 30 days:
A preview of the website (the last 30 builds are retained): To install this version:
|
|
I made all the changes you suggested, Ivy🙂 |
|
Build Succeeded 👏 Build Id: 87398b7b-210b-4f35-b84c-27da2c8a64d0 The following development artifacts have been built, and will exist for the next 30 days:
A preview of the website (the last 30 builds are retained): To install this version:
|
igooch
reviewed
Dec 12, 2023
| #### Alpha().SetCounterCapacity(key, amount) | ||
|
|
||
| This function sets the maximum capacity for a specified Counter. A capacity value of 0 indicates no capacity limit. | ||
| The function returns `true` if the capacity is successfully set, and `false` and an `error` if the operation fails. |
There was a problem hiding this comment.
Suggested change
| The function returns `true` if the capacity is successfully set, and `false` and an `error` if the operation fails. | |
| The function returns `true` if the capacity is successfully set, and `false` and an `error` if the operation fails. | |
| This function retrieves the current count for a specified Counter in the game server. This returns `-1` an `error` if | ||
| the key is not predefined. | ||
|
|
||
| {{< alert title="Note" color="info">}} |
There was a problem hiding this comment.
We can move this note up to the top under Counters And Lists and make the language more generic, since this is the case for any of the "get" operations for Counters and Lists.
There was a problem hiding this comment.
I've modified the content to make it more generic and relocated it under the title.👍🏻
|
Build Succeeded 👏 Build Id: 1cd71067-2835-4684-a803-e94ae65a122e The following development artifacts have been built, and will exist for the next 30 days:
A preview of the website (the last 30 builds are retained): To install this version:
|
igooch
reviewed
Dec 12, 2023
| silently truncated to capacity. | ||
|
|
||
| When retrieving count values through `get` operations, it's important to note that the values may not always represent | ||
| the most up-to-date value. Changes to Counters can occur through Game Server Allocation Actions as well as the SDK, |
There was a problem hiding this comment.
Suggested change
| the most up-to-date value. Changes to Counters can occur through Game Server Allocation Actions as well as the SDK, | |
| the most up-to-date value. Changes to Counters and Lists can occur through Game Server Allocation Actions as well as the SDK, |
|
|
||
| When retrieving count values through `get` operations, it's important to note that the values may not always represent | ||
| the most up-to-date value. Changes to Counters can occur through Game Server Allocation Actions as well as the SDK, | ||
| so this count may not always be accurate as it could be reading cached data. However, count will be |
There was a problem hiding this comment.
Suggested change
| so this count may not always be accurate as it could be reading cached data. However, count will be | |
| so this value may not always be accurate as it could be reading cached data. However, value will be |
|
Build Failed 😱 Build Id: 6070efbd-e29c-446d-98d5-40be6d95c0b4 To get permission to view the Cloud Build view, join the agones-discuss Google Group. |
|
Build Succeeded 👏 Build Id: dc583502-3c06-4ece-906b-bbc0817c3676 The following development artifacts have been built, and will exist for the next 30 days:
A preview of the website (the last 30 builds are retained): To install this version:
|
igooch
approved these changes
Dec 13, 2023
gongmax
reviewed
Dec 13, 2023
| by default. | ||
|
|
||
| {{< alert title="Note" color="info">}} | ||
| There is a potential race condition when count values are set from both the SDK and through the K8s API(Allocation or otherwise), |
There was a problem hiding this comment.
Suggested change
| There is a potential race condition when count values are set from both the SDK and through the K8s API(Allocation or otherwise), | |
| There is a potential race condition when count values are set from both the SDK and through the K8s API (Allocation or otherwise), |
gongmax
reviewed
Dec 13, 2023
| #### Alpha().IncrementCounter(key, amount) | ||
|
|
||
| This function increments the count of a specified Counter by a given nonnegative value amount. The function returns `false` | ||
| and an `error` if the key wasn't predefined in the GameServer resource and returns or if the Counter is already at capacity, |
There was a problem hiding this comment.
"returns or if the Counter is already...". I don't understand this part. Should it be "returns error if..."?
There was a problem hiding this comment.
The function returns false and an error if the key wasn't predefined in the GameServer resource or if the Counter is already at capacity.
gongmax
reviewed
Dec 13, 2023
gongmax
reviewed
Dec 13, 2023
|
|
||
| #### Alpha().AppendListValue(key, value) | ||
|
|
||
| This function appends a string value to a List's values, identified by the List's key(name) and the string value. |
There was a problem hiding this comment.
Suggested change
| This function appends a string value to a List's values, identified by the List's key(name) and the string value. | |
| This function appends a string value to a List's values, identified by the List's key (name) and the string value. |
gongmax
reviewed
Dec 13, 2023
|
|
||
| #### Alpha().DeleteListValue(key, value) | ||
|
|
||
| This function removes a string from a List's values using its key(name) and the specific string value. It returns an |
There was a problem hiding this comment.
Suggested change
| This function removes a string from a List's values using its key(name) and the specific string value. It returns an | |
| This function removes a string from a List's values using its key (name) and the specific string value. It returns an |
gongmax
reviewed
Dec 13, 2023
|
|
||
| This function sets the capacity for a specified List, identified by its key (name), with the capacity value required to be | ||
| between 0 and 1000. It returns an error if the key wasn't predefined in the GameServer resource. The function returns `true` | ||
| if the capacity is successfully set, or `false` and an error if the operation fails. |
There was a problem hiding this comment.
Suggested change
| if the capacity is successfully set, or `false` and an error if the operation fails. | |
| if the capacity is successfully set, or `false` and an `error` if the operation fails. |
gongmax
reviewed
Dec 13, 2023
|
|
||
| #### Alpha().GetListCapacity(key) | ||
|
|
||
| This function retrieves the capacity of a specified List using its key(name). It returns `-1` and an `error` if the key wasn't |
There was a problem hiding this comment.
Suggested change
| This function retrieves the capacity of a specified List using its key(name). It returns `-1` and an `error` if the key wasn't | |
| This function retrieves the capacity of a specified List using its key( name). It returns `-1` and an `error` if the key wasn't |
gongmax
reviewed
Dec 13, 2023
|
|
||
| #### Alpha().ListContains(key, value) | ||
|
|
||
| This function checks if a specific string value exists in a List's values, identified by the List's key(name). |
There was a problem hiding this comment.
Suggested change
| This function checks if a specific string value exists in a List's values, identified by the List's key(name). | |
| This function checks if a specific string value exists in a List's values, identified by the List's key (name). |
gongmax
reviewed
Dec 13, 2023
| #### Alpha().ListContains(key, value) | ||
|
|
||
| This function checks if a specific string value exists in a List's values, identified by the List's key(name). | ||
| The search is case-sensitive. It returns `true` if the string is found in the list, and `false` otherwise.`false` and an error |
There was a problem hiding this comment.
Suggested change
| The search is case-sensitive. It returns `true` if the string is found in the list, and `false` otherwise.`false` and an error | |
| The search is case-sensitive. It returns `true` if the string is found in the list, and `false` otherwise. `false` and an `error` |
gongmax
reviewed
Dec 13, 2023
| This function checks if a specific string value exists in a List's values, identified by the List's key(name). | ||
| The search is case-sensitive. It returns `true` if the string is found in the list, and `false` otherwise.`false` and an error | ||
| are returned if the key wasn't predefined in the GameServer resource or if there's an issue in fetching the List. | ||
| #### Alpha().GetListLength(key) |
There was a problem hiding this comment.
Suggested change
| #### Alpha().GetListLength(key) | |
| #### Alpha().GetListLength(key) |
gongmax
reviewed
Dec 13, 2023
| are returned if the key wasn't predefined in the GameServer resource or if there's an issue in fetching the List. | ||
| #### Alpha().GetListLength(key) | ||
|
|
||
| This function retrieves the number of items (length) in the Values list of a specified List, identified by the List's key(name). |
There was a problem hiding this comment.
Suggested change
| This function retrieves the number of items (length) in the Values list of a specified List, identified by the List's key(name). | |
| This function retrieves the number of items (length) in the Values list of a specified List, identified by the List's key (name). |
gongmax
reviewed
Dec 13, 2023
|
|
||
| #### Alpha().GetListValues(key) | ||
|
|
||
| This function returns all the string values from a specified List, identified by the List's key(name). It returns |
There was a problem hiding this comment.
Suggested change
| This function returns all the string values from a specified List, identified by the List's key(name). It returns | |
| This function returns all the string values from a specified List, identified by the List's key (name). It returns |
|
@gongmax, I have made changes based on your suggestion. |
|
Build Succeeded 👏 Build Id: 1bb40e36-8706-4daf-826a-0b98871cbc0f The following development artifacts have been built, and will exist for the next 30 days:
A preview of the website (the last 30 builds are retained): To install this version:
|
gongmax
approved these changes
Dec 13, 2023
5 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
What this PR does / Why we need it:
Which issue(s) this PR fixes:
Closes #
Special notes for your reviewer: