class ObjectTracker

ObjectTracker is a a kernel version of a multithreaded map container + allocator

specialized for uint32

<

--> object. It provides the standard map services

add, remove, get

&

enumerate but also the storage services of a pool allocator.

ObjectTracker fills the gap between the existing helpers:

- allocators cannot enumerate their live objects, the current solution is

to use a intrusive linked list to enumerate them which comes with 16 bytes

overhead and lookups are O(n).

- The WAVL tree supports fast lookups and iteration but each object must

pay 48+ bytes overhead, so it is only practical if the object weights upwards of

200 bytes.

The API is move-oriented, the typical lifecycle goes:

1 - Create object |o| to be tracked

2 - Move |o| into the tracker via add(o) which returns its |id|.

3 - Retrieve the object reference (via the holder) from get(id)

4 - call |o| methods via the holder

5 - Drop the holder

6 - Either remove the object from tracking via remove(id) or

goto step 3.

Using it

ObjectTracker takes two class template parameters:

A) TrackedType: the class to be stored and tracked, it must implement three

methods:

1- zx_status on_holder(uint32_t user_tag). Called when a Holder needs to

be created. If this method returns an error, the holder will not be

created and the error will be returned instead.

2- uint32_t on_tracked(). Called once the object is being tracked. The

returned value is the "user tag" included in the tracking id. See remarks

below.

3- zx_status_t on_remove(uint32_t user_tag). Called before is removed from

tracking. If this method returns an error, the object will not be removed

from the container and the error will be returned instead.

If the user_tag feature is not needed, on_tracked() and on_remove() methods can

have a no-op implementations as follows:

uint32_t on_tracked() {

return 0u;

}

zx_status_t on_remove(uint32_t) {

return ZX_OK;

}

All the above callbacks are issued with a spinlock acquired that protects the page

where the tracked object lives. Therefore, no calls to the tracker should be issued

from the callback or calls that acquire regular mutexes. Calls that acquire

spinlocks are ok.

B) HolderType: an object of this class is returned when ObjectTracker::get()

is successful. The Holder is created via the HolderType(TrackedType

&

) or the

HolderType(const TrackedType

&

) ctor. If HolderType keeps a weak reference to the

TrackedType then it must collaborate with it to prevent ObjectTracker::remove()

from succeeding by returning an error from TrackedType::on_remove().

The TrackedType has one more requirement: it must have a boring destructor

for the particular case when it is called for a moved-from state. In other words

assume a TrackedType = TFoo, then

TFoo destination;

{

// stack allocated storage for |source|.

alignas(Foo) char data[sizeof(Foo)];

TFoo* source = new (data) TFoo();

......

......

destination = std::move(*source);

avoid_dtor = true;

if (!avoid_dtor) {

source->~TFoo();

}

}

The program above is correct for the TFoo type. Note that if TFoo is not in the

moved-from state, the destructor can do all sorts of critical operations, this means

the object tracker that fail the ktl::is_trivially_destructible

<TrackedType

> test.

Using the user_tag

A user tag is a small value, cookie-like, with as many bits as the template parameter

user_tag_bits. It is provided by the tracked object during ObjectTracker::add() via the

callback on_tracked() and returned as mixed in the returned id. This tag is given back

to the tracked object during the ObjectTracker::get() in the on_holder()

callback or during ObjectTracker::remove() in the on_remove() callback.

The tracked object has full freedom how to interpret the tag, it might require to be

provided back the same tag or a different value. The ObjectTracker::encode() and

decode() static functions can be used by clients to extract or replace the tag returned

by the tracked object, except in one case, during the ObjectTracker destruction

or if triggered manually via destroy_all() the on_remove() callback is issued with

the special value kTagDestroy, which is hardcoded to be the highest value possible

for an unsigned number of size user_tag_bits.