Wc3C.net

Wc3C.net (http://www.wc3c.net/forums.php)
-   Scripts (http://www.wc3c.net/forumdisplay.php?f=737)
-   -   GroupUtils (http://www.wc3c.net/showthread.php?t=104464)

Rising_Dusk 02-05-2009 01:54 PM

GroupUtils
 
GroupUtils Library

Background:
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.

Requirements:
  • 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.
Quote:

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!

Seshiro 02-05-2009 02:53 PM

Hey Rising Dusk,

That thing here is just the CS thing, if you'd looked into the TimerUtils thread, you had seen that there is the group stack :D
Therefore i think that this is nearly useless ;)

Greez

Vexorian 02-05-2009 03:28 PM

But the CS thing blows.

Dusk, could you add a group cleaner like Griffen's it would make sense to make it GroupUtils a sort of standard if it had that. I think this also needs a double free protection, at least during debug mode.

Using SCOPE_PREFIX like that is a little exaggerated.

Rising_Dusk 02-05-2009 04:11 PM

Quote:

Originally Posted by Seshiro
That thing here is just the CS thing, if you'd looked into the TimerUtils thread, you had seen that there is the group stack :D
Therefore i think that this is nearly useless ;)

I'd never even noticed that before. After reading the TimerUtils thread, it appears that it was only for backwards compatibility and not actual usage.
Quote:

Originally Posted by Vexorian
Dusk, could you add a group cleaner like Griffen's it would make sense to make it GroupUtils a sort of standard if it had that. I think this also needs a double free protection, at least during debug mode.

Certainly. Hrm, Table is probably the most logical means for double free protection as far as I can see. Do you agree or..?
Quote:

Originally Posted by Vexorian
Using SCOPE_PREFIX like that is a little exaggerated.

Yeah, but I think it's a healthy habit to be in. :)
I can remove it if you'd prefer.

Vexorian 02-05-2009 04:18 PM

There should be a better way than table.

Captain Griffen 02-05-2009 05:03 PM

Quote:

Originally Posted by Vexorian
Dusk, could you add a group cleaner like Griffen's it would make sense to make it GroupUtils a sort of standard if it had that. I think this also needs a double free protection, at least during debug mode.


Or just add GroupRefresh, a compatability library for backward compatabilty, and then be done with it (oh, and link to my thread for the background on why you need it, then GY that).

A standard would be nice.

Rising_Dusk 02-05-2009 05:08 PM

Quote:

Originally Posted by Vexorian
There should be a better way than table.

Probably, I'll look into it.
Quote:

Originally Posted by Captain Griffen
Or just add GroupRefresh, a compatability library for backward compatabilty, and then be done with it (oh, and link to my thread for the background on why you need it, then GY that).

A standard would be nice.

I think the syntax for GroupRefresh is clean enough that a backwards compatibility library likely won't be necessary. I'll see what I can do, a standard for this thing would be big.

emjlr3 02-05-2009 07:51 PM

wasnt one of these included with cs_safety? (along with the timersafety bit)

Joker 02-05-2009 08:03 PM

So...are we supposed to call
Collapse JASS:
ForGroup()
stuff with ENUM_GROUP? I'm confuzed.

Rising_Dusk 02-05-2009 08:21 PM

You could, if you don't need to hold the group for longer than an instant. NewGroup and ReleaseGroup only make sense when you need a group for longer than a given instant. ENUM_GROUP and any group obtained with NewGroup() will work in ForGroup() calls, though.
Quote:

Originally Posted by emjlr3
wasnt one of these included with cs_safety? (along with the timersafety bit)

Probably, but the CS is obsolete. Now we have xe, but some stanardized GroupUtils is still missing from the database. I'll work on this when I get home tonight.

Captain Griffen 02-05-2009 08:46 PM

Quote:

Originally Posted by Rising_Dusk
I think the syntax for GroupRefresh is clean enough that a backwards compatibility library likely won't be necessary. I'll see what I can do, a standard for this thing would be big.


Collapse JASS:
library GroupRefresh requires GroupUtils
endlibrary

And you could also have:
Collapse JASS:
library CSSafety requires GroupUtils, TimerUtils
endlibrary

Av3n 02-05-2009 09:59 PM

If this is GroupUtilities, I'm not saying that it is necessary, it would be nice to have a Enum function that checks units in range by collision.

Just my opinion.

-Av3n

Rising_Dusk 02-05-2009 10:16 PM

Such a function could be created and then require GroupUtils.

fX_ 02-06-2009 03:12 AM

Well if groups are such hazard handles as timers and this is TimerUtils for groups and TimerUtils is like, essential, then this should be essential, too.

Captain Griffen 02-06-2009 08:53 AM

Except in 90% of cases of groups, you don't want to do this. In the other 9% of cases, you can use structs to recycle timers more efficiently.


All times are GMT. The time now is 12:06 PM.

Powered by vBulletin (Copyright ©2000 - 2019, Jelsoft Enterprises Ltd).
Hosted by www.OICcam.com
IT Support and Services provided by Executive IT Services