Official When, where, and why to put [BurstCompile], with mild under-the-hood explanation

Thanks for sharing. But still I hope official can figure out the better solution to further reduce typing like eliminate [BurstCompile] and remove ValueRO and ValueRW for foreach at ISystem while still offer same codegen and compilation speed.

 

ISystem's .ForEach (and probably Query API alike) are burst compiled by default, unless manually stated otherwise. (which is not possible for ISystems, perhaps only partially via [BurstDiscard], which I haven't tested);

Its the OnUpdate method that aren't bursted by default (at least, in 0.51 that is).
However, it can be burst compiled by marking it manually via attribute. Not everything was compatible though as of 0.51 (jobs / collection disposal, safety system, and such).

So TL;DR:
- SystemBase / ISystem -> .Run / .Schedule / .ScheduleParallel - Burst Compiled by default, no need to mark static methods if those are called from ForEach / IJobs (in some cases would actually throw errors!). Unless .WithoutBurst()
- Static methods can be burst compiled even when called outside Entities context when marked as [BurstCompile] (-> results in a function pointer)
- Jobs can be marked with [BurstCompile] to be bursted from non-system context;
- If in doubt - check Burst Inspector.


Going forward (1.0+), I think it makes sense to make OnUpdate burst compilable by default as well. Though, I'm not sure how managed code in unmanaged systems should be handled in this case.

 

In the spirit of clearing up confusion, I'd also like to ask what the difference is between the

[BurstCompile]

attribute, and the

[BurstCompatible]

attribute. Which should be used over the other in what scenarios?

 

One is direct marker of - "Hey, make this thing burstable" and also provides parameters of how to compile that (precision, synch, etc.) second is indicator that method is compatible (or not in case of NotBurstCompatible when containing type is burst compatible but something inside - not) with burst which also provides additional configuration of that capability like CompileTarget, RequiredUnityDefine, GenericTypeArguments, and generated test validates usages by that attribute and parameters. This second attribute doesn't "make" code bursted, only BurstCompileAttribute does (of course in bounds described by @elliotc-unity)

 

Alright, so the

[BurstCompile]

attribute is the more important and more functional one, and is the one I should definitely use for all my static methods that I want to be bursted, if I understand correctly.

Is it a good idea to always combine that one with a

[BurstCompatible]

attribute, for the generated validation? Or do you reckon it's not really useful to add it at all (except perhaps in rare cases where you'd actually make use of the attribute parameters) and just use

[BurstCompile]

alone?

 

Is code called from bursted code compiled in some special way? If I do this:

Code (CSharp):

1. [BurstCompile]
2. public static partial class MyBurstedMethods
3. {      
4.         [BurstCompile]
5.         public static float3 BurstedMethod(float3 x, float3 y)
6.         {
7.             return x + y;
8.         }
9. }

It will not compile as I use structs as parameters and returned type, meanwhile the same function called from some Execute will be completely fine.

 

So Bakers cannot be [BurstCompile] correct?

 

Well, technically Baker<T> itself can't be bursted like ISystem, but, jobs is there, direct Burst calls is there, and you can make mainthreaded bursted jobs, multithreaded bursted jobs for some heavy calculations in Baker<T>, moreover BakingSystem is a system which can be SystemBase with bursted jobs or ISystem (and as result completely bursted)

Code (CSharp):

1. [WorldSystemFilter(WorldSystemFilterFlags.BakingSystem)]
2.     [UpdateInGroup(typeof(PostBakingSystemGroup))]
3.     [BurstCompile]
4.     public partial struct PostBakeSystem : ISystem
5.     {
6.         public void OnCreate(ref SystemState state) { }
7.  
8.         public void OnDestroy(ref SystemState state) { }
9.  
10.         [BurstCompile]
11.         public void OnUpdate(ref  SystemState state)
12.         {
13.  
14.             foreach (var transformAspect in SystemAPI.Query<TransformAspect>())
15.             {
16.                 transformAspect.Position = -1;
17.             }
18.         }
19.     }

Authoring:


Runtime (processed by bursted BakingSystem):

 

Im just here to make the

IsBursted

function a one-liner, a.k.a. optimizing aesthetics:

Code (CSharp):

1. public static bool IsBursted => Unity.Burst.CompilerServices.Constant.IsConstantExpression(1);

You can go on now

 

Sorry, I am still confused.

I understand from examples that I need to put burstcompile in Isystem various places.

How about IAspect? If I have a function in aspect:

Public float3 GetPos()
{...}

Do I need to put [burstcomplile] above it? (I know i can do it with getter...just an example for discussion).

Also, for helper/utility class, do I need to put burstcompile also?

E.g. In a job,

int value = GameUtility.GetABC() <----do I need to put burstcompile above "Public Static Class GameUtility{...} AND above "Public Static GetABC()" static method?

Thank you.

 

If you’re calling the methods from inside Burst-compiled jobs / systems / Burst-compiled static methods, there’s nothing that needs to be done. All the applicable code will have Burst variants prepared for you, because Burst code is basically viral and requires everything that gets executed from a starting point to be Burst-compiled.
This doesn’t affect execution of the methods when run by normal managed code. You’ll effectively get two implementations for the method that run depending on whether it’s being called from a Burst-compiled job / system / other entry point or just normal managed code. If you need to make sure some specific algorithm (only static methods) works in Burst when directly called from some normal manager code, you can add BurstCompile to it which will let the framework patch the calls in the IL to the Burst version. However, it may not be worth doing this for small methods.
further reading
https://docs.unity3d.com/Packages/c...al/docs/AdvancedUsages.html#function-pointers

 

Sorry for the necro, but was just reading this and curious if this still applies:

* The reason you need to put [BurstCompile] on the declaring type as well as the static method is to reduce the time Burst needs to take scanning for what to burst. If we didn't require it on the type, it would have to go to every method of every type checking for attributes, whereas this way it can just check the type itself and move on if the type doesn't have the attribute. This applies to ISystem's as well.

Because if so, does that mean that the scaffolding generated by Rider for EG ISystem is actually incorrect because it doesn't mark the type as well?

Code (CSharp):

1.     public partial struct TestSystem : ISystem
2.     {
3.         [BurstCompile]
4.         public void OnCreate(ref SystemState state)
5.         {
6.            
7.         }
8.  
9.         [BurstCompile]
10.         public void OnUpdate(ref SystemState state)
11.         {
12.  
13.         }
14.  
15.         [BurstCompile]
16.         public void OnDestroy(ref SystemState state)
17.         {
18.  
19.         }
20.     }
21.  

 

Doesn't this mean there could be a way to provide a "burst analysis" that spits out missing [BurstCompile] attributes? (and an option to show such warnings upon making builds for example)