X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/a243b4c3535f516d05259cac06963c422d4aadc0..9bcf7dd5948ad1781a7ff203bb04e21b1dceebc7:/include/xbt/lib.h diff --git a/include/xbt/lib.h b/include/xbt/lib.h index c087513c81..e42c14a197 100644 --- a/include/xbt/lib.h +++ b/include/xbt/lib.h @@ -1,6 +1,6 @@ /* xbt/lib.h - api to a generic library */ -/* Copyright (c) 2011, 2013. The SimGrid Team. +/* Copyright (c) 2011, 2013-2014. The SimGrid Team. * All rights reserved. */ /* This program is free software; you can redistribute it and/or modify it @@ -13,6 +13,42 @@ SG_BEGIN_DECL() +/** Container for all the objects of a given type + * + * * each item is identified by a string name/identifier; + * + * * the lib itself is a dictionary from the element id to the element; + * + * * the element itself is represented aby the xbt_dictelm_t; + * + * * the element can store any number of associated facets/data structures + * (corresponding to the different layers of SimGrid or its extensions) + * in ((void**)dictelt->content)[level]; + * + * * each level is allocated in the lib with `xbt_lib_add_level`. + * + *
+ * // Define a collection for the foo objects and two associated facets: + * typedef xbt_dictelm_t foo_t; + * xbt_lib_t foo_lib = xbt_lib_new(); + * int BAR_FOO_LEVEL = xbt_lib_add_level(foo_lib, free_bar); + * int AUTH_FOO_LEVEL = xbt_lib_add_level(foo_lib, free_auth); + * + * // Store a bar: + * bar_t bar = bar_new(); + * char* id = bar_name(bar); + * xbt_lib_set(id, id, BAR_FOO_LEVEL, bar); + * + * // Find the corresponding foo and the facet again: + * foo_t foo = xbt_lib_get_elm_or_null(foo_lib, id); + * bar_t bar2 = (bar_t) xbt_lib_get_level(foo, BAR_FOO_LEVEL); + * assert(bar == bar2); + * + * // Add authentication facet for the previous object: + * auth_t auth = auth_new(); + * xbt_lib_set(foo_lib, id, AUTH_FOO_LEVEL, auth); + *+ */ typedef struct s_xbt_lib { xbt_dict_t dict; int levels;