From Kerrighed

Contents

Look up for an object 

void *kddm_find_object ( struct kddm_ns *ns      // Name space of the object to find.
                         kddm_set_id_t set_id,   // Set id of the object to find.
                         objid_t objid           // Id of the object to find.
                       );
void *_kddm_find_object ( struct kddm_set *set,   // Kddm Set of the object to find.
                          objid_t objid           // Id of the object to find.
                        );


The kddm_find_object function checks if an object is present in local memory of the node executing this function.

  • If the object is present, a pointer to the object is returned.
    • The object is frozen. A call to kddm_put_object is needed after the use of the object.
  • If the object is not present, NULL is returned.
    • The object is not frozen.


Release an object 

void kddm_put_object ( struct kddm_ns *ns      // Name space of the object to put.
                       kddm_set_id_t set_id,   // Set id of the object to put.
                       objid_t objid           // Id of the object to put.
                     );
void _kddm_put_object ( struct kddm_set *set    // Kddm Set of the object to put.
                        objid_t objid           // Id of the object to put.
                      );

The kddm_put_object function releases an object which has been acquired by the kddm_find_object, kddm_get_object or kddm_grab_object function. A call to this function after the use of the object is mandatory.


Get a readable object

kddm_get_object 

void *kddm_get_object ( struct kddm_ns *ns      // Name space of the object to get.
                        kddm_set_id_t set_id,   // Set id of the object to get.
                        objid_t objid           // Id of the object to get.
                      );
void _kddm_get_object ( struct kddm_set *set    // Kddm Set of the object to get.
                        objid_t objid           // Id of the object to get.
                      );

The kddm_get_object function return a pointer to the requested object. If the object is not present in local memory, a copy of the object is fetched from a remote node owning a copy. If the object does not exist in the cluster, a few new object is created and it's pointer is returned.

An object returned by the kddm_get_object cannot be written.


async_kddm_get_object 

void *async_kddm_get_object ( struct kddm_ns *ns      // Name space of the object to get.
                              kddm_set_id_t set_id,   // Set id of the object to get.
                              objid_t objid           // Id of the object to get.
                            );
void _async_kddm_get_object ( struct kddm_set *set    // Kddm Set of the object to get.
                              objid_t objid           // Id of the object to get.
                            );

The async_kddm_get_object is the asynchronous version of the kddm_get_object. This function returns immediately, even if the object is not locally present. If the object was present, its address is returned, otherwise NULL is returned. In any cases a call to kddm_put_object is needed after a call to this function.


kddm_get_object_no_ft 

void *kddm_get_object_no_ft ( struct kddm_ns *ns      // Name space of the object to get.
                              kddm_set_id_t set_id,   // Set id of the object to get.
                              objid_t objid           // Id of the object to get.
                            );
void _kddm_get_object_no_ft ( struct kddm_set *set    // Kddm Set of the object to get.
                              objid_t objid           // Id of the object to get.
                            );

The kddm_get_object_no_ft function returns a pointer to the requested object, only if the object already exist somewhere in the cluster. If the object does not exist, NULL is returned. In any cases a call to kddm_put_object is needed after a call to this function.


kddm_get_object_no_lock 

void *kddm_get_object_no_lock ( struct kddm_ns *ns      // Name space of the object to get.
                                kddm_set_id_t set_id,   // Set id of the object to get.
                                objid_t objid           // Id of the object to get.
                              );
void _kddm_get_object_no_lock ( struct kddm_set *set    // Kddm Set of the object to get.
                                objid_t objid           // Id of the object to get.
                              );

The kddm_get_object_no_lock is the same as the kddm_get_object except the returned object is not locked. So a call to kddm_put_object is not needed after the use of the object.

Use this function very carefully ! Since the object is not locked it can be invalidated at any time. You can only use this function when you are sure the object cannot be invalidated or if you are using a "tricky" IO linker which does not free objects on invalidations.


Get a writable object

kddm_grab_object 

void *kddm_grab_object ( struct kddm_ns *ns      // Name space of the object to grab.
                         kddm_set_id_t set_id,   // Set id of the object to grab.
                         objid_t objid           // Id of the object to grab.
                       );
void _kddm_grab_object ( struct kddm_set *set    // Kddm Set of the object to grab.
		         objid_t objid           // Id of the object to grab.
                       );

The kddm_grab_object function return a pointer to the requested object. If the object is not present in local memory, a copy of the object is fetched from a remote node owning a copy. If the object does not exist in the cluster, a few new object is created and it's pointer is returned. A call to this function ensure that the local copy of the object is the only one existing in the while cluster.

An object returned by the kddm_grab_object can be written.


async_kddm_grab_object 

void *async_kddm_grab_object ( struct kddm_ns *ns      // Name space of the object to grab.
                               kddm_set_id_t set_id,   // Set id of the object to grab.
                               objid_t objid           // Id of the object to grab.
                             );
void _async_kddm_grab_object ( struct kddm_set *set    // Kddm Set of the object to grab.
                               objid_t objid           // Id of the object to grab.
                             );

The async_kddm_grab_object is the asynchronous version of the kddm_grab_object. This function returns immediately, even if the object is not locally present. If the object was present, its address is returned, otherwise NULL is returned. In any cases a call to kddm_put_object is needed after a call to this function.


kddm_grab_object_no_ft 

void *kddm_grab_object_no_ft ( struct kddm_ns *ns      // Name space of the object to grab.
                               kddm_set_id_t set_id,   // Set id of the object to grab.
                               objid_t objid           // Id of the object to grab.
                             );
void _kddm_grab_object_no_ft ( struct kddm_set *set    // Kddm Set of the object to grab.
                               objid_t objid           // Id of the object to grab.
                             );

The kddm_grab_object_no_ft function returns a pointer to the requested object, only if the object already exist somewhere in the cluster. If the object does not exist, NULL is returned. In any cases a call to kddm_put_object is needed after a call to this function.


kddm_grab_object_no_lock 

void *kddm_grab_object_no_lock ( struct kddm_ns *ns      // Name space of the object to grab.
                                kddm_set_id_t set_id,   // Set id of the object to grab.
                                objid_t objid           // Id of the object to grab.
                              );
void _kddm_grab_object_no_lock ( struct kddm_set *set    // Kddm Set of the object to grab.
                                 objid_t objid           // Id of the object to grab.
                               );

The kddm_grab_object_no_lock is the same as the kddm_grab_object except the returned object is not locked. So a call to kddm_put_object is not needed after the use of the object.

Use this function very carefully ! Since the object is not locked it can be invalidated at any time. You can only use this function when you are sure the object cannot be invalidated or if you are using a "tricky" IO linker which does not free objects on invalidations.


kddm_try_grab_object 

void *kddm_try_grab_object ( struct kddm_ns *ns      // Name space of the object to grab.
                             kddm_set_id_t set_id,   // Set id of the object to grab.
                             objid_t objid           // Id of the object to grab.
                           );
void _kddm_try_grab_object ( struct kddm_set *set    // Kddm Set of the object to grab.
		             objid_t objid           // Id of the object to grab.
                           );

The kddm_try_grab_object function behaves as the kddm_grab_object function, except it returns a pointer to the requested object only if the object if not currently grabbed by another process. Otherwise, -EBUSY is returned.

  • If the function returns -EBUSY no call to kddm_put_object is needed.
  • If the function returns a valid pointer, a call to kddm_put_object after the use of the object is mandatory.

Destroy an object

kddm_remove_object 

int kddm_remove_object ( struct kddm_ns *ns      // Name space of the object to remove.
                         kddm_set_id_t set_id,   // Set id of the object to remove.
                         objid_t objid,          // Id of the object to remove.
                       );


int _kddm_remove_object ( struct kddm_set *set    // Kddm Set of the object to remove.
                          objid_t objid           // Id of the object to remove.
                        );

The kddm_remove_object function removes an object from a KDDM set cluster wide. After a call to this function all copies of this object have been destroyed.

kddm_remove_frozen_object 

int kddm_remove_frozen_object ( struct kddm_ns *ns      // Name space of the object to remove.
                                kddm_set_id_t set_id,   // Set id of the object to remove.
                                objid_t objid,          // Id of the object to remove.
                              );


int _kddm_remove_frozen_object ( struct kddm_set *set    // Kddm Set of the object to remove.
                                 objid_t objid           // Id of the object to remove.
                               );

The kddm_remove_frozen_object function does the same thing than the kddm_remove_object function. The only difference is this function can be called on an object which is currently frozen through a get, grab or find function. This is useful to remove an object atomically depending on the content of an object.


Flush an object from local memory 

int kddm_flush_object ( struct kddm_ns *ns      // Name space of the object to flush.
                        kddm_set_id_t set_id,   // Set id of the object to flush.
                        objid_t objid,          // Id of the object to flush.
			kerrighed_node_t dest   // The node to send the object if needed.
                      );


int _kddm_flush_object ( struct kddm_set *set    // Kddm Set of the object to flush.
                         objid_t objid           // Id of the object to flush.
  	                 kerrighed_node_t dest   // The node to send the object if needed.
                       );

The kddm_flush_object function removes an object from the local memory but make sure at least one copy exist somewhere. If other copies exist on remote nodes, the local copy is simply destroyed. If no other copies exist, the local copy is moved to the dest node passed to the function.

  • Return 0 if the object has been removed from local memory.
  • Return -1 if the object has not been removed (object not present)

Synchronize an object 

int kddm_sync_frozen_object ( struct kddm_ns *ns      // Name space of the object to synchronize.
                              kddm_set_id_t set_id,   // Set id of the object to synchronize.
                              objid_t objid,          // Id of the object to synchronize.
                            );


int _kddm_sync_frozen_object ( struct kddm_set *set    // Kddm Set of the object to synchronize.
                               objid_t objid           // Id of the object to synchronize.
                             );

The kddm_sync_frozen_object function synchronizes an object with its attached physical device, if any. On the node linked to the given object (locally or remotly) the IO linker sync_object function is called. Object data is sent to the remote linked node if needed.

  • This function must be called within a KDDM critical section (between a get/grab and a put).
Retrieved from "http://www.kerrighed.org/wiki/index.php/KernelDevelKddmInterface"