# `AcediaObject` and `AcediaActor` Acedia defines its own base classes for both actor (`AcediaActor`) and non-actor objects (`AcediaObject`), better integrated into Acedia's infrastructure. Here we will go over everything you need to understand them.`Object` and `Actor`. ## Who is responsible for objects? If you've already read [safety rules](./safety.md) (and you should have), then you already know about the importance of deallocation. But which objects exactly are you supposed to deallocate? Understanding what objects you are responsible for is likely the most important concept to get when working with Acedia. There are two main guidelines: * **If function returns an object (as a return value or as an `out` argument) - then this object must be deallocated by whoever called that function.** If you've called `_.text.Empty()`, then you must deallocate the `MutableText`object it returned. Conversely, if you are implementing function that returns an object, then you must not deallocate it yourself. In fact, you are expected not to use that object at all, since now you can't know when it will be deallocated. * **Functions do not deallocate their arguments.** If you pass an object as an argument to a function - you can expect that it won't be deallocated during that call. It might get *modified*, but not *deallocated*. And, again, when implementing your own function - you should not deallocate its arguments either. However, these guidelines should be treated as *default assumptions* and not *hard rules*. ### Exceptions First guideline, for example, can be broken if returned object is supposed to be shared: `_.players.GetPlayers()` returns array with references to *player objects* (`array`) that aren't supposed to ever be deallocated. Similarly, Acedia's collections operate by different rules: they might still consider themselves responsible for objects returned with `GetItem()`. Second guideline can also be broken by some of the methods for the sake of convenience. If you need to turn a `Text` object `textToConvert` into a `string`, then you can either do: ```unrealscript if (textToConvert != none) { result = textToConvert.ToPlainString(); textToConvert.FreeSelf(); } ``` or simply call `_.text.ToString()` that automatically deallocates its argument: `result = _.text.ToString(textToConvert)`. > Any such exceptions are documented (or at least should be), so simply read > the docs for functions you're using. > If they don't mention anything about how their arguments or return values > should be treated - assume above stated guidelines. ## `MemoryAPI` The majority, if not all, of the Acedia's objects you will be using are going to be created by specialized methods like `_.text.FromString()`, `_.collections.EmptyDynamicArray()` or `_.time.StartTimer()` and can be deallocated with `self.FreeSelf()` method. However, that won't be enough if you want to create and allocate your own classes, for that you'll need the help of `MemoryAPI`. They are less powerful than `new` keyword and `Spawn()` function, but perform certain background work, necessary for Acedia to function and **you should always use them for creating Acedia's objects**. Ultimately, all Acedia's objects and actors are created with `_.memory.Allocate()` and "destroyed" with `_.memory.Free()`. For example, here is how new `Parser` is created with `_.text.NewParser()`: ```unrealscript public final function Parser NewParser() { return Parser(_.memory.Allocate(class'Parser')); } ``` and `self.FreeSelf()` is actually defined in `AcediaObject` and `AcediaActor` as follows (ignore parts about life versions for now, they will be explained in sections below): ```unrealscript public final function FreeSelf(optional int lifeVersion) { if (lifeVersion <= 0 || lifeVersion == GetLifeVersion()) { _.memory.Free(self); } } ``` These two functions are the most important ones in `MemoryAPI`, but it contains several more useful ones: | Function | Description | | -------- | ----------- | | `Allocate(class