X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=lustre%2Finclude%2Fcl_object.h;h=91b32c9d3067790933c752a1a3e2d92cd94c68da;hb=818b881ea0dbcb0b0e7a022d2cef4e6e72f32d23;hp=958324e9421a3f8872969d1f727c217afa0c7f4f;hpb=118bb27a7b2acce63cd0cf52af10f53b95f2a732;p=fs%2Flustre-release.git diff --git a/lustre/include/cl_object.h b/lustre/include/cl_object.h index 958324e..91b32c9 100644 --- a/lustre/include/cl_object.h +++ b/lustre/include/cl_object.h @@ -26,7 +26,7 @@ * GPL HEADER END */ /* - * Copyright 2008 Sun Microsystems, Inc. All rights reserved + * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. * Use is subject to license terms. */ /* @@ -383,16 +383,16 @@ struct cl_object_header { */ /** @{ */ /** Lock protecting page tree. */ - spinlock_t coh_page_guard; + cfs_spinlock_t coh_page_guard; /** Lock protecting lock list. */ - spinlock_t coh_lock_guard; + cfs_spinlock_t coh_lock_guard; /** @} locks */ /** Radix tree of cl_page's, cached for this object. */ struct radix_tree_root coh_tree; /** # of pages in radix tree. */ unsigned long coh_pages; /** List of cl_lock's granted for this object. */ - struct list_head coh_locks; + cfs_list_t coh_locks; /** * Parent object. It is assumed that an object has a well-defined @@ -409,7 +409,7 @@ struct cl_object_header { * * \todo XXX this can be read/write lock if needed. */ - spinlock_t coh_attr_guard; + cfs_spinlock_t coh_attr_guard; /** * Number of objects above this one: 0 for a top-object, 1 for its * sub-object, etc. @@ -421,18 +421,18 @@ struct cl_object_header { * Helper macro: iterate over all layers of the object \a obj, assigning every * layer top-to-bottom to \a slice. */ -#define cl_object_for_each(slice, obj) \ - list_for_each_entry((slice), \ - &(obj)->co_lu.lo_header->loh_layers, \ - co_lu.lo_linkage) +#define cl_object_for_each(slice, obj) \ + cfs_list_for_each_entry((slice), \ + &(obj)->co_lu.lo_header->loh_layers, \ + co_lu.lo_linkage) /** * Helper macro: iterate over all layers of the object \a obj, assigning every * layer bottom-to-top to \a slice. */ -#define cl_object_for_each_reverse(slice, obj) \ - list_for_each_entry_reverse((slice), \ - &(obj)->co_lu.lo_header->loh_layers, \ - co_lu.lo_linkage) +#define cl_object_for_each_reverse(slice, obj) \ + cfs_list_for_each_entry_reverse((slice), \ + &(obj)->co_lu.lo_header->loh_layers, \ + co_lu.lo_linkage) /** @} cl_object */ #ifndef pgoff_t @@ -696,13 +696,13 @@ enum cl_page_flags { */ struct cl_page { /** Reference counter. */ - atomic_t cp_ref; + cfs_atomic_t cp_ref; /** An object this page is a part of. Immutable after creation. */ struct cl_object *cp_obj; /** Logical page index within the object. Immutable after creation. */ pgoff_t cp_index; /** List of slices. Immutable after creation. */ - struct list_head cp_layers; + cfs_list_t cp_layers; /** Parent page, NULL for top-level page. Immutable after creation. */ struct cl_page *cp_parent; /** Lower-layer page. NULL for bottommost page. Immutable after @@ -716,11 +716,11 @@ struct cl_page { /** * Linkage of pages within some group. Protected by * cl_page::cp_mutex. */ - struct list_head cp_batch; + cfs_list_t cp_batch; /** Mutex serializing membership of a page in a batch. */ - struct mutex cp_mutex; + cfs_mutex_t cp_mutex; /** Linkage of pages within cl_req. */ - struct list_head cp_flight; + cfs_list_t cp_flight; /** Transfer error. */ int cp_error; @@ -753,6 +753,8 @@ struct cl_page { struct lu_ref_link *cp_queue_ref; /** Per-page flags from enum cl_page_flags. Protected by a VM lock. */ unsigned cp_flags; + /** Assigned if doing a sync_io */ + struct cl_sync_io *cp_sync_io; }; /** @@ -769,7 +771,7 @@ struct cl_page_slice { struct cl_object *cpl_obj; const struct cl_page_operations *cpl_ops; /** Linkage into cl_page::cp_layers. Immutable after creation. */ - struct list_head cpl_linkage; + cfs_list_t cpl_linkage; }; /** @@ -830,8 +832,9 @@ struct cl_page_operations { * \see cl_page_own() * \see vvp_page_own(), lov_page_own() */ - void (*cpo_own)(const struct lu_env *env, - const struct cl_page_slice *slice, struct cl_io *io); + int (*cpo_own)(const struct lu_env *env, + const struct cl_page_slice *slice, + struct cl_io *io, int nonblock); /** Called when ownership it yielded. Optional. * * \see cl_page_disown() @@ -859,7 +862,7 @@ struct cl_page_operations { const struct cl_page_slice *slice, struct cl_io *io); /** - * Announces whether the page contains valid data or not by @uptodate. + * Announces whether the page contains valid data or not by \a uptodate. * * \see cl_page_export() * \see vvp_page_export() @@ -1061,7 +1064,7 @@ struct cl_page_operations { do { \ static DECLARE_LU_CDEBUG_PRINT_INFO(__info, mask); \ \ - if (cdebug_show(mask, DEBUG_SUBSYSTEM)) { \ + if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) { \ cl_page_print(env, &__info, lu_cdebug_printer, page); \ CDEBUG(mask, format , ## __VA_ARGS__); \ } \ @@ -1074,7 +1077,7 @@ do { \ do { \ static DECLARE_LU_CDEBUG_PRINT_INFO(__info, mask); \ \ - if (cdebug_show(mask, DEBUG_SUBSYSTEM)) { \ + if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) { \ cl_page_header_print(env, &__info, lu_cdebug_printer, page); \ CDEBUG(mask, format , ## __VA_ARGS__); \ } \ @@ -1298,6 +1301,11 @@ struct cl_lock_descr { __u64 cld_gid; /** Lock mode. */ enum cl_lock_mode cld_mode; + /** + * flags to enqueue lock. A combination of bit-flags from + * enum cl_enq_flags. + */ + __u32 cld_enq_flags; }; #define DDESCR "%s(%d):[%lu, %lu]" @@ -1334,15 +1342,15 @@ const char *cl_lock_mode_name(const enum cl_lock_mode mode); * | | V * | | HELD<---------+ * | | | | - * | | | | + * | | | | cl_use_try() * | | cl_unuse_try() | | * | | | | - * | | V | cached - * | +------------>UNLOCKING (*) | lock found - * | | | - * | cl_unuse_try() | | + * | | V ---+ + * | +------------>INTRANSIT (D) <--+ * | | | + * | cl_unuse_try() | | cached lock found * | | | cl_use_try() + * | | | * | V | * +------------------CACHED---------+ * | @@ -1361,6 +1369,8 @@ const char *cl_lock_mode_name(const enum cl_lock_mode mode); * * (C) is the point where Cancellation call-back is invoked. * + * (D) is the transit state which means the lock is changing. + * * Transition to FREEING state is possible from any other state in the * diagram in case of unrecoverable error. * @@ -1379,9 +1389,6 @@ const char *cl_lock_mode_name(const enum cl_lock_mode mode); * handled, and is in ENQUEUED state after enqueue to S2 has been sent (note * that in this case, sub-locks move from state to state, and top-lock remains * in the same state). - * - * Separate UNLOCKING state is needed to maintain an invariant that in HELD - * state lock is immediately ready for use. */ enum cl_lock_state { /** @@ -1403,10 +1410,16 @@ enum cl_lock_state { */ CLS_HELD, /** - * Lock is in the transition from CLS_HELD to CLS_CACHED. Lock is in - * this state only while cl_unuse() is executing against it. + * This state is used to mark the lock is being used, or unused. + * We need this state because the lock may have several sublocks, + * so it's impossible to have an atomic way to bring all sublocks + * into CLS_HELD state at use case, or all sublocks to CLS_CACHED + * at unuse case. + * If a thread is referring to a lock, and it sees the lock is in this + * state, it must wait for the lock. + * See state diagram for details. */ - CLS_UNLOCKING, + CLS_INTRANSIT, /** * Lock granted, not used. */ @@ -1427,9 +1440,7 @@ enum cl_lock_flags { /** cancellation is pending for this lock. */ CLF_CANCELPEND = 1 << 1, /** destruction is pending for this lock. */ - CLF_DOOMED = 1 << 2, - /** State update is pending. */ - CLF_STATE = 1 << 3 + CLF_DOOMED = 1 << 2 }; /** @@ -1465,7 +1476,7 @@ struct cl_lock_closure { * List of enclosed locks, so far. Locks are linked here through * cl_lock::cll_inclosure. */ - struct list_head clc_list; + cfs_list_t clc_list; /** * True iff closure is in a `wait' mode. This determines what * cl_lock_enclosure() does when a lock L to be added to the closure @@ -1491,14 +1502,14 @@ struct cl_lock_closure { */ struct cl_lock { /** Reference counter. */ - atomic_t cll_ref; + cfs_atomic_t cll_ref; /** List of slices. Immutable after creation. */ - struct list_head cll_layers; + cfs_list_t cll_layers; /** * Linkage into cl_lock::cll_descr::cld_obj::coh_locks list. Protected * by cl_lock::cll_descr::cld_obj::coh_lock_guard. */ - struct list_head cll_linkage; + cfs_list_t cll_linkage; /** * Parameters of this lock. Protected by * cl_lock::cll_descr::cld_obj::coh_lock_guard nested within @@ -1523,10 +1534,14 @@ struct cl_lock { * * \see osc_lock_enqueue_wait(), lov_lock_cancel(), lov_sublock_wait(). */ - struct mutex cll_guard; + cfs_mutex_t cll_guard; cfs_task_t *cll_guarder; int cll_depth; + /** + * the owner for INTRANSIT state + */ + cfs_task_t *cll_intransit_owner; int cll_error; /** * Number of holds on a lock. A hold prevents a lock from being @@ -1553,7 +1568,11 @@ struct cl_lock { * * \see cl_lock_closure */ - struct list_head cll_inclosure; + cfs_list_t cll_inclosure; + /** + * Confict lock at queuing time. + */ + struct cl_lock *cll_conflict; /** * A list of references to this lock, for debugging. */ @@ -1584,7 +1603,7 @@ struct cl_lock_slice { struct cl_object *cls_obj; const struct cl_lock_operations *cls_ops; /** Linkage into cl_lock::cll_layers. Immutable after creation. */ - struct list_head cls_linkage; + cfs_list_t cls_linkage; }; /** @@ -1656,8 +1675,9 @@ struct cl_lock_operations { * usual return values of lock state-machine methods, this can return * -ESTALE to indicate that lock cannot be returned to the cache, and * has to be re-initialized. + * unuse is a one-shot operation, so it must NOT return CLO_WAIT. * - * \see ccc_lock_unlock(), lov_lock_unlock(), osc_lock_unlock() + * \see ccc_lock_unuse(), lov_lock_unuse(), osc_lock_unuse() */ int (*clo_unuse)(const struct lu_env *env, const struct cl_lock_slice *slice); @@ -1729,7 +1749,7 @@ struct cl_lock_operations { const struct cl_lock_slice *slice, struct cl_lock_closure *closure); /** - * Executed top-to-bottom when lock description changes (e.g., as a + * Executed bottom-to-top when lock description changes (e.g., as a * result of server granting more generous lock than was requested). * * \see lovsub_lock_modify() @@ -1768,7 +1788,7 @@ struct cl_lock_operations { do { \ static DECLARE_LU_CDEBUG_PRINT_INFO(__info, mask); \ \ - if (cdebug_show(mask, DEBUG_SUBSYSTEM)) { \ + if (cfs_cdebug_show(mask, DEBUG_SUBSYSTEM)) { \ cl_lock_print(env, &__info, lu_cdebug_printer, lock); \ CDEBUG(mask, format , ## __VA_ARGS__); \ } \ @@ -1796,12 +1816,12 @@ do { \ * @{ */ struct cl_page_list { - unsigned pl_nr; - struct list_head pl_pages; - cfs_task_t *pl_owner; + unsigned pl_nr; + cfs_list_t pl_pages; + cfs_task_t *pl_owner; }; -/** \addtogroup cl_page_list cl_page_list +/** * A 2-queue of pages. A convenience data-type for common use case, 2-queue * contains an incoming page list and an outgoing page list. */ @@ -1870,8 +1890,8 @@ enum cl_io_type { CIT_READ, /** write system call */ CIT_WRITE, - /** truncate system call */ - CIT_TRUNC, + /** truncate, utime system calls */ + CIT_SETATTR, /** * page fault handling */ @@ -1946,7 +1966,7 @@ struct cl_io_slice { * linkage into a list of all slices for a given cl_io, hanging off * cl_io::ci_layers. Immutable after creation. */ - struct list_head cis_linkage; + cfs_list_t cis_linkage; }; @@ -2143,14 +2163,9 @@ enum cl_enq_flags { */ struct cl_io_lock_link { /** linkage into one of cl_lockset lists. */ - struct list_head cill_linkage; + cfs_list_t cill_linkage; struct cl_lock_descr cill_descr; struct cl_lock *cill_lock; - /** - * flags to enqueue lock for this IO. A combination of bit-flags from - * enum cl_enq_flags. - */ - __u32 cill_enq_flags; /** optional destructor */ void (*cill_fini)(const struct lu_env *env, struct cl_io_lock_link *link); @@ -2187,11 +2202,11 @@ struct cl_io_lock_link { */ struct cl_lockset { /** locks to be acquired. */ - struct list_head cls_todo; + cfs_list_t cls_todo; /** locks currently being processed. */ - struct list_head cls_curr; + cfs_list_t cls_curr; /** locks acquired. */ - struct list_head cls_done; + cfs_list_t cls_done; }; /** @@ -2213,6 +2228,7 @@ struct cl_io_rw_common { int crw_nonblock; }; + /** * State for io. * @@ -2235,7 +2251,7 @@ struct cl_io { */ struct cl_io *ci_parent; /** List of slices. Immutable after creation. */ - struct list_head ci_layers; + cfs_list_t ci_layers; /** list of locks (to be) acquired by this io. */ struct cl_lockset ci_lockset; /** lock requirements, this is just a help info for sublayers. */ @@ -2248,18 +2264,17 @@ struct cl_io { union { struct cl_rd_io { struct cl_io_rw_common rd; - int rd_is_sendfile; } ci_rd; struct cl_wr_io { struct cl_io_rw_common wr; int wr_append; } ci_wr; struct cl_io_rw_common ci_rw; - struct cl_truncate_io { - /** new size to which file is truncated */ - size_t tr_size; - struct obd_capa *tr_capa; - } ci_truncate; + struct cl_setattr_io { + struct ost_lvb sa_attr; + unsigned int sa_valid; + struct obd_capa *sa_capa; + } ci_setattr; struct cl_fault_io { /** page index within file. */ pgoff_t ft_index; @@ -2433,16 +2448,16 @@ struct cl_req_obj { * req's pages. */ struct cl_req { - enum cl_req_type crq_type; + enum cl_req_type crq_type; /** A list of pages being transfered */ - struct list_head crq_pages; + cfs_list_t crq_pages; /** Number of pages in cl_req::crq_pages */ - unsigned crq_nrpages; + unsigned crq_nrpages; /** An array of objects which pages are in ->crq_pages */ - struct cl_req_obj *crq_o; + struct cl_req_obj *crq_o; /** Number of elements in cl_req::crq_objs[] */ - unsigned crq_nrobjs; - struct list_head crq_layers; + unsigned crq_nrobjs; + cfs_list_t crq_layers; }; /** @@ -2451,7 +2466,7 @@ struct cl_req { struct cl_req_slice { struct cl_req *crs_req; struct cl_device *crs_dev; - struct list_head crs_linkage; + cfs_list_t crs_linkage; const struct cl_req_operations *crs_ops; }; @@ -2463,16 +2478,16 @@ struct cl_req_slice { struct cache_stats { const char *cs_name; /** how many entities were created at all */ - atomic_t cs_created; + cfs_atomic_t cs_created; /** how many cache lookups were performed */ - atomic_t cs_lookup; + cfs_atomic_t cs_lookup; /** how many times cache lookup resulted in a hit */ - atomic_t cs_hit; + cfs_atomic_t cs_hit; /** how many entities are in the cache right now */ - atomic_t cs_total; + cfs_atomic_t cs_total; /** how many entities in the cache are actively used (and cannot be * evicted) right now */ - atomic_t cs_busy; + cfs_atomic_t cs_busy; }; /** These are not exported so far */ @@ -2498,8 +2513,8 @@ struct cl_site { */ struct cache_stats cs_pages; struct cache_stats cs_locks; - atomic_t cs_pages_state[CPS_NR]; - atomic_t cs_locks_state[CLS_NR]; + cfs_atomic_t cs_pages_state[CPS_NR]; + cfs_atomic_t cs_locks_state[CLS_NR]; }; int cl_site_init (struct cl_site *s, struct cl_device *top); @@ -2625,6 +2640,7 @@ int cl_conf_set (const struct lu_env *env, struct cl_object *obj, const struct cl_object_conf *conf); void cl_object_prune (const struct lu_env *env, struct cl_object *obj); void cl_object_kill (const struct lu_env *env, struct cl_object *obj); +int cl_object_has_locks (struct cl_object *obj); /** * Returns true, iff \a o0 and \a o1 are slices of the same object. @@ -2644,11 +2660,17 @@ void cl_page_gang_lookup(const struct lu_env *env, struct cl_object *obj, struct cl_io *io, pgoff_t start, pgoff_t end, - struct cl_page_list *plist); + struct cl_page_list *plist, + int nonblock, + int *resched); struct cl_page *cl_page_find (const struct lu_env *env, struct cl_object *obj, pgoff_t idx, struct page *vmpage, enum cl_page_type type); +struct cl_page *cl_page_find_sub (const struct lu_env *env, + struct cl_object *obj, + pgoff_t idx, struct page *vmpage, + struct cl_page *parent); void cl_page_get (struct cl_page *page); void cl_page_put (const struct lu_env *env, struct cl_page *page); @@ -2676,6 +2698,8 @@ const struct cl_page_slice *cl_page_at(const struct cl_page *page, int cl_page_own (const struct lu_env *env, struct cl_io *io, struct cl_page *page); +int cl_page_own_try (const struct lu_env *env, + struct cl_io *io, struct cl_page *page); void cl_page_assume (const struct lu_env *env, struct cl_io *io, struct cl_page *page); void cl_page_unassume (const struct lu_env *env, @@ -2749,7 +2773,6 @@ struct cl_lock *cl_lock_peek(const struct lu_env *env, const struct cl_io *io, const char *scope, const void *source); struct cl_lock *cl_lock_request(const struct lu_env *env, struct cl_io *io, const struct cl_lock_descr *need, - __u32 enqflags, const char *scope, const void *source); struct cl_lock *cl_lock_at_page(const struct lu_env *env, struct cl_object *obj, struct cl_page *page, struct cl_lock *except, @@ -2769,8 +2792,14 @@ void cl_lock_release (const struct lu_env *env, struct cl_lock *lock, const char *scope, const void *source); void cl_lock_user_add (const struct lu_env *env, struct cl_lock *lock); int cl_lock_user_del (const struct lu_env *env, struct cl_lock *lock); -int cl_lock_compatible(const struct cl_lock *lock1, - const struct cl_lock *lock2); + +enum cl_lock_state cl_lock_intransit(const struct lu_env *env, + struct cl_lock *lock); + +void cl_lock_extransit(const struct lu_env *env, struct cl_lock *lock, + enum cl_lock_state state); + +int cl_lock_is_intransit(struct cl_lock *lock); /** \name statemachine statemachine * Interface to lock state machine consists of 3 parts: @@ -2812,14 +2841,14 @@ int cl_enqueue_try(const struct lu_env *env, struct cl_lock *lock, struct cl_io *io, __u32 flags); int cl_unuse_try (const struct lu_env *env, struct cl_lock *lock); int cl_wait_try (const struct lu_env *env, struct cl_lock *lock); -int cl_use_try (const struct lu_env *env, struct cl_lock *lock); +int cl_use_try (const struct lu_env *env, struct cl_lock *lock, int atomic); /** @} statemachine */ void cl_lock_signal (const struct lu_env *env, struct cl_lock *lock); int cl_lock_state_wait (const struct lu_env *env, struct cl_lock *lock); void cl_lock_state_set (const struct lu_env *env, struct cl_lock *lock, enum cl_lock_state state); -int cl_queue_match (const struct list_head *queue, +int cl_queue_match (const cfs_list_t *queue, const struct cl_lock_descr *need); void cl_lock_mutex_get (const struct lu_env *env, struct cl_lock *lock); @@ -2879,7 +2908,7 @@ void cl_io_end (const struct lu_env *env, struct cl_io *io); int cl_io_lock_add (const struct lu_env *env, struct cl_io *io, struct cl_io_lock_link *link); int cl_io_lock_alloc_add(const struct lu_env *env, struct cl_io *io, - struct cl_lock_descr *descr, int enqflags); + struct cl_lock_descr *descr); int cl_io_read_page (const struct lu_env *env, struct cl_io *io, struct cl_page *page); int cl_io_prepare_write(const struct lu_env *env, struct cl_io *io, @@ -2889,6 +2918,9 @@ int cl_io_commit_write (const struct lu_env *env, struct cl_io *io, int cl_io_submit_rw (const struct lu_env *env, struct cl_io *io, enum cl_req_type iot, struct cl_2queue *queue, enum cl_req_priority priority); +int cl_io_submit_sync (const struct lu_env *env, struct cl_io *io, + enum cl_req_type iot, struct cl_2queue *queue, + enum cl_req_priority priority, long timeout); void cl_io_rw_advance (const struct lu_env *env, struct cl_io *io, size_t nob); int cl_io_cancel (const struct lu_env *env, struct cl_io *io, @@ -2903,7 +2935,14 @@ static inline int cl_io_is_append(const struct cl_io *io) return io->ci_type == CIT_WRITE && io->u.ci_wr.wr_append; } -int cl_io_is_sendfile(const struct cl_io *io); +/** + * True, iff \a io is a truncate(2). + */ +static inline int cl_io_is_trunc(const struct cl_io *io) +{ + return io->ci_type == CIT_SETATTR && + (io->u.ci_setattr.sa_valid & ATTR_SIZE); +} struct cl_io *cl_io_top(struct cl_io *io); @@ -2928,13 +2967,13 @@ do { \ * Iterate over pages in a page list. */ #define cl_page_list_for_each(page, list) \ - list_for_each_entry((page), &(list)->pl_pages, cp_batch) + cfs_list_for_each_entry((page), &(list)->pl_pages, cp_batch) /** * Iterate over pages in a page list, taking possible removals into account. */ #define cl_page_list_for_each_safe(page, temp, list) \ - list_for_each_entry_safe((page), (temp), &(list)->pl_pages, cp_batch) + cfs_list_for_each_entry_safe((page), (temp), &(list)->pl_pages, cp_batch) void cl_page_list_init (struct cl_page_list *plist); void cl_page_list_add (struct cl_page_list *plist, struct cl_page *page); @@ -2993,16 +3032,17 @@ void cl_req_completion(const struct lu_env *env, struct cl_req *req, int ioret); */ struct cl_sync_io { /** number of pages yet to be transferred. */ - atomic_t csi_sync_nr; + cfs_atomic_t csi_sync_nr; /** completion to be signaled when transfer is complete. */ - struct completion csi_sync_completion; + cfs_waitq_t csi_waitq; /** error code. */ - int csi_sync_rc; + int csi_sync_rc; }; void cl_sync_io_init(struct cl_sync_io *anchor, int nrpages); int cl_sync_io_wait(const struct lu_env *env, struct cl_io *io, - struct cl_page_list *queue, struct cl_sync_io *anchor); + struct cl_page_list *queue, struct cl_sync_io *anchor, + long timeout); void cl_sync_io_note(struct cl_sync_io *anchor, int ioret); /** @} cl_sync_io */ @@ -3033,12 +3073,15 @@ void cl_sync_io_note(struct cl_sync_io *anchor, int ioret); * longer used environments instead of destroying them; * * - there is a notion of "current" environment, attached to the kernel - * data structure representing current thread (current->journal_info in - * Linux kernel). Top-level lustre code allocates an environment and makes - * it current, then calls into non-lustre code, that in turn calls lustre - * back. Low-level lustre code thus called can fetch environment created - * by the top-level code and reuse it, avoiding additional environment - * allocation. + * data structure representing current thread Top-level lustre code + * allocates an environment and makes it current, then calls into + * non-lustre code, that in turn calls lustre back. Low-level lustre + * code thus called can fetch environment created by the top-level code + * and reuse it, avoiding additional environment allocation. + * Right now, three interfaces can attach the cl_env to running thread: + * - cl_env_get + * - cl_env_implant + * - cl_env_reexit(cl_env_reenter had to be called priorly) * * \see lu_env, lu_context, lu_context_key * @{ */