Thread: GroupUtils
View Single Post
Old 02-05-2009, 01:54 PM   #1
Obscurity, the Art

Projects Director
Project Leader: OD
Join Date: Feb 2006
Posts: 9,729

Submissions (27)

Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)Rising_Dusk has a reputation beyond repute (1192)

Hero Contest #3 - 1st PlaceApproved Map: Desert of ExileApproved Map: Advent of the ZenithHero Contest #2 - 1st PlaceHero Contest - Third place>

Send a message via AIM to Rising_Dusk Send a message via MSN to Rising_Dusk
Default GroupUtils

GroupUtils Library

This is a simple library that includes a group stack for dynamic groups, a global group that can be used for enumerations, and a pair of TRUE/FALSE boolexprs for preventing the null boolexpr leak in enumerations backwards compatibility with old maps that use them. Since the 1.24c patch, the null boolexpr leak in enumerations no longer exists. It also implements Griffen's method of GroupRefresh, which makes this a nice, all-encompassing utility set standard for group handling. Lastly, this library has means to group units in an area of effect while considering collision, something the GroupEnumUnitsInRange native does not do.

  • None
Requirements (Optional):Credits:Code:
Expand Library:

Function List:
This library provides the following functions to the user.
  • function NewGroup takes nothing returns group
  • function ReleaseGroup takes group g returns boolean
  • function GroupRefresh takes group g returns nothing
  • function GroupEnumUnitsInArea takes group whichGroup, real x, real y, real radius, boolexpr filter returns nothing
  • function GroupUnitsInArea takes group whichGroup, real x, real y, real radius returns nothing
This library also provides the following global variables to the user.
  • group ENUM_GROUP
  • boolexpr BOOLEXPR_TRUE
  • boolexpr BOOLEXPR_FALSE
The reason why GroupRefresh exists is best explained by Griffen here. It is quoted below for the readers' convenience.
Originally Posted by Captain Griffen
Units that are removed from the game or decay while part of a group remain in the hash table. They also appear to remain in the list (which can cause issues with FirstOfGroup loops).

Therefore, if units are not removed manually from the group before this happens, there is a minor leak, and the CPU cost of many group operations increases dramatically. Verification is in this thread here.

NB: This only applies to where a group has units in it for longer than an instant, and where those units may decay / be removed. Most uses of groups are not vulnerable to that (most uses you should be using a static group and a boolexpr these days - those are completely unaffected).

Fortunately, GroupClear solves the problem, enabling the creation of a function that can be called on a group and flushes out all of the shadow units in it. The cost is pretty much O(n), where n is the number of real units in the group (rather than shadows).

GroupRefresh does not affect the group in a noticeable way, aside from removing the shadow references in the hash table, which speeds up most operations (see the link above for further details). The only effect it will have on outputs is on FirstOfGroup, which can return null when it comes to a shadow reference in the list, even if there are real units after it. GroupRefresh clears those out, so makes FirstOfGroup act properly again.

More frequent calls of GroupRefresh will reduce CPU costs of most operations involving groups whose usage makes them vulnerable to this, but will incur a higher CPU cost of its own. Look at the benchmarks on the link above and decide for yourself what the best balance is.
Backwards Compatibility:
In the event that you used one of the libraries this has deprecated, the following backwards compatibility libraries have been provided for your convenience. Simply replace the old library with the respective library below and it will work fine.
Expand GroupRefresh:
Expand CSSafety:
Expand BoolexprUtils:

Thanks guys, hopefully this helps streamline group handling!
Rising_Dusk is offline   Reply With Quote
Sponsored Links - Login to hide this ad!