⭐️ Features

Tip

Reactive primitives are synchronous event loops which use a few tricks to essentially eliminate heap allocations in performance critical hot paths.

📖 Example Usage

Note

TheAutoValue<int> and the binding to itAutoValue<int>.Binding need to be cleaned up when you're finished to avoid memory leaks.

// Enemy gameplay logicpublicsealedclassEnemy:IDisposable{// mutable observable value private to this classprivatereadonlyAutoValue<int>_health=new(100);// immutable view of the value for outside subscriberspublicIAutoValue<int>Health=>_health;publicvoidTakeDamage(intdamage){// enemy can't take more damage than it has healthvarappliedDamage=Math.Min(Math.Abs(damage),_health.Value);// bindings will be notified when this goes into effect_health.Value-=appliedDamage;}publicvoidDispose(){// release references to any bindings to the health value so they can be GC'd_health.Dispose();}}// Enemy visualization logicpublicsealedclassEnemyView:IDisposable{publicEnemyEnemy{get;}publicAutoValue<int>.BindingBinding{get;}publicEnemyView(Enemyenemy){Enemy=enemy;// listen to changes in the enemy's healthBinding=enemy.Health.Bind();Binding.OnValue(OnHealthChanged);}publicvoidOnHealthChanged(inthealth){// update the health bar UI, etc.}publicvoidDispose(){Binding.Dispose();// stop listening}}

Tip

By convention, objects which own the reactive primitive — the_health field in this example — retain a reference to the primitive itself and expose it publicly as a read-only reference that can be used to bind to it.

privatereadonlyAutoValue<int>_health=new(100);// private mutable viewpublicIAutoValue<int>Health=> _health;// public read-only view

📦 Installation

dotnet add package Chickensoft.Sync

🔂 AutoValue

// hang onto the value for as long as you want to change it, then call Dispose()// when you're done with itvarautoValue=newAutoValue<Animal>(newCat("Pickles"));// hang onto the binding for as long as you want to observe, then call Dispose()// on itusingvarbinding=autoValue.Bind();// you can chain binding callback registration for ease-of-usebinding// called whenever the value changes.OnValue(animal=>Console.WriteLine($"Observing animal{animal}"))// only called for Dog values.OnValue((Dogdog)=>Console.WriteLine($"Observing dog{dog.Name}"))// only called for Cat values.OnValue((Catcat)=>Console.WriteLine($"Observing cat{cat.Name}"));autoValue.Value=newDog("Brisket");// Observing animal Brisket// Observing dog BrisketautoValue.Value=newCat("Chibi");// Observing animal Chibi// Observing cat Chibi

binding// only observe dog values.OnValue((Dogdog)=>Console.WriteLine($"Observing dog{dog.Name}"))// or if you'd rather specify the type as the generic argument instead of as// the lambda argument.OnValue<Dog>(dog=>Console.WriteLine($"Observing dog{dog.Name}"))

binding.OnValue((Dogdog)=>Console.WriteLine($"Observing dog with B name{dog.Name}"),condition: dog=>dog.Name.StartsWith('B')// customize what you care about);

🔢 AutoList

varautoList=newAutoList<Animal>([newCat("Pickles"),newDog("Cookie"),newDog("Brisket"),newCat("Sven")]);usingvarbinding=autoList.Bind();binding.OnAdd(animal=>Console.WriteLine($"Animal added:{animal}"))// or with its index.OnAdd((index,animal)=>Console.WriteLine($"Animal added at index{index}:{animal}")).OnClear(()=>Console.WriteLine("List cleared"))// only called when a Dog is added.OnAdd((Dogdog)=>Console.WriteLine($"Dog added:{dog.Name}"))// only called when a Cat is removed.OnRemove((Catcat)=>Console.WriteLine($"Cat removed:{cat.Name}")).OnUpdate((previous,current)=>Console.WriteLine($"Animal updated from{previous} to{current}")).OnUpdate((Dogprevious,Dogcurrent)=>Console.WriteLine($"Dog updated from{previous.Name} to{current.Name}")).OnUpdate((Dogprevious,Catcurrent)=>Console.WriteLine($"Dog{previous.Name} replaced by Cat{current.Name}"))// or with its index.OnUpdate((Dogprevious,Catcurrent,intindex)=>Console.WriteLine($"Dog at index{index} updated from{previous} to Cat{current}"));autoList.Add(newDog("Chibi"));autoList.RemoveAt(0);

varautoListWithComparer=newAutoList<Animal>([],newMyAnimalComparer());

🧦 AutoSet

Note

Due to memory allocation considerations,AutoSet<T> does not implement the fullISet<T> interfaces, which would require temporary collections to be created to track the result of batch operations.

varautoSet=newAutoSet<Animal>(newHashSet<Animal>{newCat("Pickles"),newDog("Cookie"),newDog("Brisket"),newCat("Sven")});usingvarbinding=autoSet.Bind();binding.OnAdd(animal=>Console.WriteLine($"Animal added:{animal}")).OnRemove(animal=>Console.WriteLine($"Animal removed:{animal}"))// only called when a Dog is added.OnAdd((Dogdog)=>Console.WriteLine($"Dog added:{dog.Name}"))// only called when a Cat is removed.OnRemove((Catcat)=>Console.WriteLine($"Cat removed:{cat.Name}")).OnClear(()=>Console.WriteLine("Set cleared"));autoSet.Add(newDog("Chibi"));autoSet.Remove(newCat("Pickles"));

🗺️ AutoMap

varautoMap=newAutoMap<string,Animal>(newDictionary<string,Animal>{["Pickles"]=newCat("Pickles"),["Cookie"]=newDog("Cookie"),["Brisket"]=newDog("Brisket"),["Sven"]=newCat("Sven")});usingvarbinding=autoMap.Bind();binding.OnAdd((key,animal)=>Console.WriteLine($"Animal added:{key} ->{animal}")).OnRemove((key,animal)=>Console.WriteLine($"Animal removed:{key} ->{animal}")).OnUpdate((key,previous,current)=>Console.WriteLine($"Animal updated:{key} from{previous} to{current}")).OnClear(()=>Console.WriteLine("Map cleared"));autoMap["Chibi"]=newDog("Chibi");autoMap.Remove("Pickles");autoMap["Brisket"]=newPoodle("Brisket");

💰 AutoCache

Caution

When pushing a value of typeDog which derives fromAnimal,TryGetValue<Animal>() will not return the last valueupdated of typeDog. If you desire to get the lastAnimal value updated, you will have to useUpdate<Animal>(new Dog())instead. Although Binding notifications forOnUpdate<Dog> orOnUpdate<Animal> will still be called regardless of the type pushed.

Note

WhileAutoCache does support reference types, consider using value types instead when initializing new instances onupdate to avoid allocating unnecessary memory that would need to be immediately collected by the garbage collector.Using value types where possible helps avoid stuttering and hitches by reducing the amount of work that the garbagecollector needs to do to clean up reference types on the heap.

readonlyrecordstructUpdateName(stringDogName);varautoCache=newAutoCache();usingvarbinding=autoCache.Bind();binding.OnUpdate<UpdateName>((name)=>Console.WriteLine($"Name Updated:{name}"))autoCache.Update(newUpdateName("Pickles"));autoCache.Update(newUpdateName("Sven"));// After each update, the OnUpdate callback will be called.if(autoCache.TryGetValue<UpdateName>(outvarupdate)){// This would print out "Last received dog name: Sven"Console.WriteLine($"Last received dog name:{update.DogName}"}binding.OnUpdate<Animal>((animal)=>Console.WriteLine($"Animal Updated:{animal.Name}"));// Store and broadcast a Mouse by its less-specific supertype, AnimalautoCache.Update<Animal>(newMouse("Hamtaro"));autoCache.Update(newDog("Cookie"));autoCache.Update(newCat("Pickles"));// OnUpdate<Animal> will be called 3 times.//See the caution note above for more informationautoCache.TryGetValue<Animal>(outvaranimal)// animal will be the Mouse - HamtaroautoCache.TryGetValue<Dog>(outvardog)// animal will be the Dog - CookieautoCache.TryGetValue<Cat>(outvarcat)// animal will be the Cat - Pickles

🧰 Build Your Own Reactive Primitives

Stubbing it Out

publicinterfaceIAutoValue<T>:IAutoObject<AutoValue<T>.Binding>{TValue{get;}}publicsealedclassAutoValue<T>:IAutoValue<T>{publicclassBinding:SyncBinding{internalBinding(ISyncSubjectsubject):base(subject){}}}

Tip

By convention, we nest the binding in the reactive primitive class itself so that it can access private members of the primitive, as well as any of their generic type parameters.

Atomic Operations

Note

Later, we'll implement a method that allows us to know when it's time to actually change the value. This is howSyncSubject is able to protect us fromreentrancy issues.

publicsealedclassAutoValue<T>:IAutoValue<T>{// Atomic operationsprivatereadonlyrecordstructUpdateOp(TValue);// ... binding classprivateT_value;privatereadonlySyncSubject_subject;publicTValue{get=>_value;set=>_subject.Perform(newUpdateOp(value));}publicAutoValue(Tvalue){_value=value;// create a new sync subject that will notify us when it's time to perform// the atomic operations we schedule_subject=newSyncSubject(this);}publicBindingBind()=>newBinding(_subject);publicvoidClearBindings()=>_subject.ClearBindings();publicvoidDispose()=>_subject.Dispose();}

Performing an Atomic Operation

publicsealedclassAutoValue<T>:IAutoValue<T>,IPerform<AutoValue<T>.UpdateOp>{// Atomic operationsprivatereadonlyrecordstructUpdateOp(TValue);// BroadcastspublicreadonlyrecordstructUpdateBroadcast(TValue);// ... binding class// other members// Actually perform the atomic operationvoidIPerform<UpdateOp>.Perform(inUpdateOpop){if(_value!=op.Value){// only update if it's differentreturn;}_value=op.Value;// announce change to relevant binding callbacks_subject.Broadcast(newUpdateBroadcast(op.Value));}}

Binding Implementation

publicsealedclassAutoValue<T>:IAutoValue<T>,IPerform<AutoValue<T>.UpdateOp>,IPerform<AutoValue<T>.SyncOp>{// Atomic operationsprivatereadonlyrecordstructUpdateOp(TValue);privatereadonlyrecordstructSyncOp(Action<T>Callback);// BroadcastspublicreadonlyrecordstructUpdateBroadcast(TValue);publicclassBinding:SyncBinding{internalBinding(ISyncSubjectsubject):base(subject){}publicBindingOnValue(Action<T>callback){AddCallback((inUpdateBroadcastbroadcast)=>callback(broadcast.Value));// invoke binding as soon as possible after it's added to give it the// current value immediately. different reactive primitives may or may not// want to do this, depending on their desired behavior._subject!.Perform(newSyncOp(callback));returnthis;// to let the developer chain callback registration}}// ... other members shown above// Perform the "sync" operation to invoke a callback with the current value// when a binding is first added. This mimics a ReactiveX BehaviorSubject.voidIPerform<SyncOp>.Perform(inSyncOpop)=>op.Callback(_value);}

varautoValue=newAutoValue<int>(42);usingvarbinding=autoValue.Bind();binding.OnValue(value=>Console.WriteLine($"Value changed to{value}"));

Note

TheactualAutoValue<T> implementation has to account for a custom comparer, conditional bindings, and derived types, but it's otherwise almost identical.

If you're building your own reactive primitives, take a look at the full source code forAutoValue<T>,AutoList<T>,AutoSet<T>, andAutoMap<TKey, TValue> for more examples.

🙋‍♀️ Why?

🐣 Simple

🏎️ Performance

✅ Correct By Default

Note

Unless you are building absolutely massive systems, picking correctness and ergonomics over absolute performance will most likely increase the chance of success, since it makes refactoring simpler and safer.