HazardPointer

Object Hierarchy:

Description:

[ Compact ]
public class HazardPointer<G>

Hazard pointer is a method of protecting a pointer shared by many threads. If you want to use atomic pointer that may be freed you should use following code:

	 string *shared_pointer = ...;
	 HazardPointer<string> hptr = HazardPointer.get_hazard_pointer (&shared_pointer);
	 // my_string contains value from shared_pinter. It is valid as long as hptr is alive.
	 unowned string my_string = ptr.get ();
	 // instead of delete
	 ptr.release ((ptr) => {string *sptr = ptr;string ref = (owned)sptr;});
	 });

In some cases you may use helper methods which might involve copying of object (and are unsafe for unowned objects):

	 Gtk.Window *window = ...;
	 Gtk.Window? local_window = HazardPointer.get_pointer (&window);
	 HazardPointer.set_pointer (&window, ...)
	 local_window = HazardPointer.exchange_pointer (&window, null);
	 HazardPointer.compare_and_exchange (&window, null, local_window);

The class also provides helper methods if least significant bits are used for storing flags.

HazardPointers are not thread-safe (unless documentation states otherwise).

Namespace: Gee

Package: gee-0.8

Content:

Classes:

Context - Create a new context. User does not need to create explicitly however it might be benefitial if he is about to issue bunch of commands he might consider it benefitial to fine-tune the creation of contexts.

Enums:

Policy - Policy determines what happens on exit from Context.
ReleasePolicy - Release policy determines what happens with object freed by Policy.TRY_RELEASE and Policy.RELEASE.

Static methods:

public static bool compare_and_exchange_pointer<G> (unowned G** aptr, G old_ptr, owned G _new_ptr, size_t mask = 0, size_t old_mask = 0, size_t new_mask = 0)
Compares and exchanges objects.
public static HazardPointer<G>? exchange_hazard_pointer<G> (unowned G** aptr, owned G new_ptr, size_t mask = 0, size_t new_mask = 0, out size_t old_mask = null)
Exchange objects safely.
public static G exchange_pointer<G> (unowned G** aptr, owned G new_ptr, size_t mask = 0, size_t new_mask = 0, out size_t old_mask = null)
Exchange objects safely.
public static HazardPointer<G>? get_hazard_pointer<G> (unowned G** aptr, size_t mask = 0, out size_t mask_out = null)
Gets hazard pointer from atomic pointer safely.
public static G get_pointer<G> (unowned G** aptr, size_t mask = 0, out size_t mask_out = null)
Copy an object from atomic pointer.
public static void set_default_policy (Policy policy)
Sets default policy (i.e. default policy for user-created contexts). The policy must be concrete and should not be blocking.
public static void set_pointer<G> (unowned G** aptr, owned G new_ptr, size_t mask = 0, size_t new_mask = 0)
Sets object safely
public static bool set_release_policy (ReleasePolicy policy)
Sets release (i.e. how exactly the released objects arefreed).
public static void set_thread_exit_policy (Policy policy)
Sets thread exit policy (i.e. default policy for the top-most Context). The policy must be concrete and should not be unsafe.

Creation methods:

public HazardPointer (unowned G* ptr)
Creates a hazard pointer for a pointer.

Methods:

public unowned G @get (bool other_thread = false)
Gets the pointer hold by hazard pointer.
public void release (owned DestroyNotify notify)
Free the pointer.