1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
13 use back::link::mangle_internal_name_by_path_and_seq;
14 use driver::config::FullDebugInfo;
17 use middle::mem_categorization::Typer;
18 use middle::trans::adt;
19 use middle::trans::base::*;
20 use middle::trans::build::*;
21 use middle::trans::cleanup::{CleanupMethods, ScopeId};
22 use middle::trans::common::*;
23 use middle::trans::datum::{Datum, DatumBlock, Expr, Lvalue, rvalue_scratch_datum};
24 use middle::trans::debuginfo;
25 use middle::trans::expr;
26 use middle::trans::type_of::*;
27 use middle::trans::type_::Type;
29 use util::ppaux::Repr;
30 use util::ppaux::ty_to_string;
32 use arena::TypedArena;
36 // ___Good to know (tm)__________________________________________________
38 // The layout of a closure environment in memory is
39 // roughly as follows:
41 // struct rust_opaque_box { // see rust_internal.h
42 // unsigned ref_count; // obsolete (part of @T's header)
43 // fn(void*) *drop_glue; // destructor (for proc)
44 // rust_opaque_box *prev; // obsolete (part of @T's header)
45 // rust_opaque_box *next; // obsolete (part of @T's header)
46 // struct closure_data {
53 // Note that the closure is itself a rust_opaque_box. This is true
54 // even for ~fn and ||, because we wish to keep binary compatibility
55 // between all kinds of closures. The allocation strategy for this
56 // closure depends on the closure type. For a sendfn, the closure
57 // (and the referenced type descriptors) will be allocated in the
58 // exchange heap. For a fn, the closure is allocated in the task heap
59 // and is reference counted. For a block, the closure is allocated on
62 // ## Opaque closures and the embedded type descriptor ##
64 // One interesting part of closures is that they encapsulate the data
65 // that they close over. So when I have a ptr to a closure, I do not
66 // know how many type descriptors it contains nor what upvars are
67 // captured within. That means I do not know precisely how big it is
68 // nor where its fields are located. This is called an "opaque
71 // Typically an opaque closure suffices because we only manipulate it
72 // by ptr. The routine Type::at_box().ptr_to() returns an appropriate
73 // type for such an opaque closure; it allows access to the box fields,
74 // but not the closure_data itself.
76 // But sometimes, such as when cloning or freeing a closure, we need
77 // to know the full information. That is where the type descriptor
78 // that defines the closure comes in handy. We can use its take and
79 // drop glue functions to allocate/free data as needed.
81 // ## Subtleties concerning alignment ##
83 // It is important that we be able to locate the closure data *without
84 // knowing the kind of data that is being bound*. This can be tricky
85 // because the alignment requirements of the bound data affects the
86 // alignment requires of the closure_data struct as a whole. However,
87 // right now this is a non-issue in any case, because the size of the
88 // rust_opaque_box header is always a multiple of 16-bytes, which is
89 // the maximum alignment requirement we ever have to worry about.
91 // The only reason alignment matters is that, in order to learn what data
92 // is bound, we would normally first load the type descriptors: but their
93 // location is ultimately depend on their content! There is, however, a
94 // workaround. We can load the tydesc from the rust_opaque_box, which
95 // describes the closure_data struct and has self-contained derived type
96 // descriptors, and read the alignment from there. It's just annoying to
97 // do. Hopefully should this ever become an issue we'll have monomorphized
98 // and type descriptors will all be a bad dream.
100 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102 pub struct EnvValue {
103 action: ast::CaptureClause,
108 pub fn to_string(&self, ccx: &CrateContext) -> String {
109 format!("{}({})", self.action, self.datum.to_string(ccx))
113 // Given a closure ty, emits a corresponding tuple ty
114 pub fn mk_closure_tys(tcx: &ty::ctxt,
115 bound_values: &[EnvValue])
117 // determine the types of the values in the env. Note that this
118 // is the actual types that will be stored in the map, not the
119 // logical types as the user sees them, so by-ref upvars must be
120 // converted to ptrs.
121 let bound_tys = bound_values.iter().map(|bv| {
123 ast::CaptureByValue => bv.datum.ty,
124 ast::CaptureByRef => ty::mk_mut_ptr(tcx, bv.datum.ty)
127 let cdata_ty = ty::mk_tup(tcx, bound_tys);
128 debug!("cdata_ty={}", ty_to_string(tcx, cdata_ty));
132 fn tuplify_box_ty(tcx: &ty::ctxt, t: ty::t) -> ty::t {
133 let ptr = ty::mk_imm_ptr(tcx, ty::mk_i8());
134 ty::mk_tup(tcx, vec!(ty::mk_uint(), ty::mk_nil_ptr(tcx), ptr, ptr, t))
137 fn allocate_cbox<'blk, 'tcx>(bcx: Block<'blk, 'tcx>,
138 store: ty::TraitStore,
140 -> Result<'blk, 'tcx> {
141 let _icx = push_ctxt("closure::allocate_cbox");
144 // Allocate and initialize the box:
145 let cbox_ty = tuplify_box_ty(tcx, cdata_ty);
147 ty::UniqTraitStore => {
148 malloc_raw_dyn_proc(bcx, cbox_ty)
150 ty::RegionTraitStore(..) => {
151 let llbox = alloc_ty(bcx, cbox_ty, "__closure");
152 Result::new(bcx, llbox)
157 pub struct ClosureResult<'blk, 'tcx: 'blk> {
158 llbox: ValueRef, // llvalue of ptr to closure
159 cdata_ty: ty::t, // type of the closure data
160 bcx: Block<'blk, 'tcx> // final bcx
163 // Given a block context and a list of tydescs and values to bind
164 // construct a closure out of them. If copying is true, it is a
165 // heap allocated closure that copies the upvars into environment.
166 // Otherwise, it is stack allocated and copies pointers to the upvars.
167 pub fn store_environment<'blk, 'tcx>(bcx: Block<'blk, 'tcx>,
168 bound_values: Vec<EnvValue> ,
169 store: ty::TraitStore)
170 -> ClosureResult<'blk, 'tcx> {
171 let _icx = push_ctxt("closure::store_environment");
175 // compute the type of the closure
176 let cdata_ty = mk_closure_tys(tcx, bound_values.as_slice());
178 // cbox_ty has the form of a tuple: (a, b, c) we want a ptr to a
179 // tuple. This could be a ptr in uniq or a box or on stack,
181 let cbox_ty = tuplify_box_ty(tcx, cdata_ty);
182 let cboxptr_ty = ty::mk_ptr(tcx, ty::mt {ty:cbox_ty, mutbl:ast::MutImmutable});
183 let llboxptr_ty = type_of(ccx, cboxptr_ty);
185 // If there are no bound values, no point in allocating anything.
186 if bound_values.is_empty() {
187 return ClosureResult {llbox: C_null(llboxptr_ty),
192 // allocate closure in the heap
193 let Result {bcx: bcx, val: llbox} = allocate_cbox(bcx, store, cdata_ty);
195 let llbox = PointerCast(bcx, llbox, llboxptr_ty);
196 debug!("tuplify_box_ty = {}", ty_to_string(tcx, cbox_ty));
198 // Copy expr values into boxed bindings.
200 for (i, bv) in bound_values.into_iter().enumerate() {
201 debug!("Copy {} into closure", bv.to_string(ccx));
203 if ccx.sess().asm_comments() {
204 add_comment(bcx, format!("Copy {} into closure",
205 bv.to_string(ccx)).as_slice());
208 let bound_data = GEPi(bcx, llbox, [0u, abi::box_field_body, i]);
211 ast::CaptureByValue => {
212 bcx = bv.datum.store_to(bcx, bound_data);
214 ast::CaptureByRef => {
215 Store(bcx, bv.datum.to_llref(), bound_data);
220 ClosureResult { llbox: llbox, cdata_ty: cdata_ty, bcx: bcx }
223 // Given a context and a list of upvars, build a closure. This just
224 // collects the upvars and packages them up for store_environment.
225 fn build_closure<'blk, 'tcx>(bcx0: Block<'blk, 'tcx>,
226 freevar_mode: ast::CaptureClause,
227 freevars: &Vec<ty::Freevar>,
228 store: ty::TraitStore)
229 -> ClosureResult<'blk, 'tcx> {
230 let _icx = push_ctxt("closure::build_closure");
232 // If we need to, package up the iterator body to call
235 // Package up the captured upvars
236 let mut env_vals = Vec::new();
237 for freevar in freevars.iter() {
238 let datum = expr::trans_local_var(bcx, freevar.def);
239 env_vals.push(EnvValue {action: freevar_mode, datum: datum});
242 store_environment(bcx, env_vals, store)
245 // Given an enclosing block context, a new function context, a closure type,
246 // and a list of upvars, generate code to load and populate the environment
247 // with the upvars and type descriptors.
248 fn load_environment<'blk, 'tcx>(bcx: Block<'blk, 'tcx>,
250 freevars: &Vec<ty::Freevar>,
251 store: ty::TraitStore)
252 -> Block<'blk, 'tcx> {
253 let _icx = push_ctxt("closure::load_environment");
255 // Don't bother to create the block if there's nothing to load
256 if freevars.len() == 0 {
260 // Load a pointer to the closure data, skipping over the box header:
261 let llcdata = at_box_body(bcx, cdata_ty, bcx.fcx.llenv.unwrap());
263 // Store the pointer to closure data in an alloca for debug info because that's what the
264 // llvm.dbg.declare intrinsic expects
265 let env_pointer_alloca = if bcx.sess().opts.debuginfo == FullDebugInfo {
266 let alloc = alloc_ty(bcx, ty::mk_mut_ptr(bcx.tcx(), cdata_ty), "__debuginfo_env_ptr");
267 Store(bcx, llcdata, alloc);
273 // Populate the upvars from the environment
275 for freevar in freevars.iter() {
276 let mut upvarptr = GEPi(bcx, llcdata, [0u, i]);
278 ty::RegionTraitStore(..) => { upvarptr = Load(bcx, upvarptr); }
279 ty::UniqTraitStore => {}
281 let def_id = freevar.def.def_id();
283 bcx.fcx.llupvars.borrow_mut().insert(def_id.node, upvarptr);
284 for &env_pointer_alloca in env_pointer_alloca.iter() {
285 debuginfo::create_captured_var_metadata(
301 fn load_unboxed_closure_environment<'blk, 'tcx>(
302 bcx: Block<'blk, 'tcx>,
303 arg_scope_id: ScopeId,
304 freevars: &Vec<ty::Freevar>,
305 closure_id: ast::DefId)
306 -> Block<'blk, 'tcx> {
307 let _icx = push_ctxt("closure::load_environment");
309 if freevars.len() == 0 {
313 // Special case for small by-value selfs.
314 let self_type = self_type_for_unboxed_closure(bcx.ccx(), closure_id);
315 let kind = kind_for_unboxed_closure(bcx.ccx(), closure_id);
316 let llenv = if kind == ty::FnOnceUnboxedClosureKind &&
317 !arg_is_indirect(bcx.ccx(), self_type) {
318 let datum = rvalue_scratch_datum(bcx,
320 "unboxed_closure_env");
321 store_ty(bcx, bcx.fcx.llenv.unwrap(), datum.val, self_type);
322 assert!(freevars.len() <= 1);
325 bcx.fcx.llenv.unwrap()
328 for (i, freevar) in freevars.iter().enumerate() {
329 let upvar_ptr = GEPi(bcx, llenv, [0, i]);
330 let def_id = freevar.def.def_id();
331 bcx.fcx.llupvars.borrow_mut().insert(def_id.node, upvar_ptr);
333 if kind == ty::FnOnceUnboxedClosureKind {
334 bcx.fcx.schedule_drop_mem(arg_scope_id,
336 node_id_type(bcx, def_id.node))
343 fn fill_fn_pair(bcx: Block, pair: ValueRef, llfn: ValueRef, llenvptr: ValueRef) {
344 Store(bcx, llfn, GEPi(bcx, pair, [0u, abi::fn_field_code]));
345 let llenvptr = PointerCast(bcx, llenvptr, Type::i8p(bcx.ccx()));
346 Store(bcx, llenvptr, GEPi(bcx, pair, [0u, abi::fn_field_box]));
349 pub fn trans_expr_fn<'blk, 'tcx>(bcx: Block<'blk, 'tcx>,
350 store: ty::TraitStore,
355 -> Block<'blk, 'tcx> {
358 * Translates the body of a closure expression.
363 * - `id`: The id of the closure expression.
364 * - `cap_clause`: information about captured variables, if any.
365 * - `dest`: where to write the closure value, which must be a
369 let _icx = push_ctxt("closure::trans_expr_fn");
371 let dest_addr = match dest {
372 expr::SaveIn(p) => p,
374 return bcx; // closure construction is non-side-effecting
380 let fty = node_id_type(bcx, id);
381 let s = tcx.map.with_path(id, |path| {
382 mangle_internal_name_by_path_and_seq(path, "closure")
384 let llfn = decl_internal_rust_fn(ccx, fty, s.as_slice());
386 // set an inline hint for all closures
387 set_inline_hint(llfn);
389 let freevar_mode = tcx.capture_mode(id);
390 let freevars: Vec<ty::Freevar> =
391 ty::with_freevars(tcx, id, |fv| fv.iter().map(|&fv| fv).collect());
397 } = build_closure(bcx, freevar_mode, &freevars, store);
402 bcx.fcx.param_substs,
410 |bcx, _| load_environment(bcx, cdata_ty, &freevars, store));
411 fill_fn_pair(bcx, dest_addr, llfn, llbox);
415 /// Returns the LLVM function declaration for an unboxed closure, creating it
416 /// if necessary. If the ID does not correspond to a closure ID, returns None.
417 pub fn get_or_create_declaration_if_unboxed_closure(ccx: &CrateContext,
418 closure_id: ast::DefId)
419 -> Option<ValueRef> {
420 if !ccx.tcx().unboxed_closures.borrow().contains_key(&closure_id) {
421 // Not an unboxed closure.
425 match ccx.unboxed_closure_vals().borrow().find(&closure_id) {
427 debug!("get_or_create_declaration_if_unboxed_closure(): found \
434 let function_type = ty::mk_unboxed_closure(ccx.tcx(),
437 let symbol = ccx.tcx().map.with_path(closure_id.node, |path| {
438 mangle_internal_name_by_path_and_seq(path, "unboxed_closure")
441 let llfn = decl_internal_rust_fn(ccx, function_type, symbol.as_slice());
443 // set an inline hint for all closures
444 set_inline_hint(llfn);
446 debug!("get_or_create_declaration_if_unboxed_closure(): inserting new \
447 closure {} (type {})",
449 ccx.tn().type_to_string(val_ty(llfn)));
450 ccx.unboxed_closure_vals().borrow_mut().insert(closure_id, llfn);
455 pub fn trans_unboxed_closure<'blk, 'tcx>(
456 mut bcx: Block<'blk, 'tcx>,
461 -> Block<'blk, 'tcx> {
462 let _icx = push_ctxt("closure::trans_unboxed_closure");
464 debug!("trans_unboxed_closure()");
466 let closure_id = ast_util::local_def(id);
467 let llfn = get_or_create_declaration_if_unboxed_closure(
469 closure_id).unwrap();
471 let unboxed_closures = bcx.tcx().unboxed_closures.borrow();
472 let function_type = unboxed_closures.get(&closure_id)
475 let function_type = ty::mk_closure(bcx.tcx(), function_type);
477 let freevars: Vec<ty::Freevar> =
478 ty::with_freevars(bcx.tcx(), id, |fv| fv.iter().map(|&fv| fv).collect());
479 let freevars_ptr = &freevars;
481 trans_closure(bcx.ccx(),
485 bcx.fcx.param_substs,
488 ty::ty_fn_args(function_type),
489 ty::ty_fn_ret(function_type),
490 ty::ty_fn_abi(function_type),
494 load_unboxed_closure_environment(bcx,
500 // Don't hoist this to the top of the function. It's perfectly legitimate
501 // to have a zero-size unboxed closure (in which case dest will be
502 // `Ignore`) and we must still generate the closure body.
503 let dest_addr = match dest {
504 expr::SaveIn(p) => p,
506 debug!("trans_unboxed_closure() ignoring result");
511 let repr = adt::represent_type(bcx.ccx(), node_id_type(bcx, id));
513 // Create the closure.
514 for (i, freevar) in freevars_ptr.iter().enumerate() {
515 let datum = expr::trans_local_var(bcx, freevar.def);
516 let upvar_slot_dest = adt::trans_field_ptr(bcx,
521 bcx = datum.store_to(bcx, upvar_slot_dest);
523 adt::trans_set_discr(bcx, &*repr, dest_addr, 0);
528 pub fn get_wrapper_for_bare_fn(ccx: &CrateContext,
532 is_local: bool) -> ValueRef {
534 let def_id = match def {
535 def::DefFn(did, _, _) | def::DefStaticMethod(did, _, _) |
536 def::DefVariant(_, did, _) | def::DefStruct(did) => did,
538 ccx.sess().bug(format!("get_wrapper_for_bare_fn: \
539 expected a statically resolved fn, got \
545 match ccx.closure_bare_wrapper_cache().borrow().find(&fn_ptr) {
546 Some(&llval) => return llval,
552 debug!("get_wrapper_for_bare_fn(closure_ty={})", closure_ty.repr(tcx));
554 let f = match ty::get(closure_ty).sty {
555 ty::ty_closure(ref f) => f,
557 ccx.sess().bug(format!("get_wrapper_for_bare_fn: \
558 expected a closure ty, got {}",
559 closure_ty.repr(tcx)).as_slice());
563 let name = ty::with_path(tcx, def_id, |path| {
564 mangle_internal_name_by_path_and_seq(path, "as_closure")
566 let llfn = if is_local {
567 decl_internal_rust_fn(ccx, closure_ty, name.as_slice())
569 decl_rust_fn(ccx, closure_ty, name.as_slice())
572 ccx.closure_bare_wrapper_cache().borrow_mut().insert(fn_ptr, llfn);
574 // This is only used by statics inlined from a different crate.
576 // Don't regenerate the wrapper, just reuse the original one.
580 let _icx = push_ctxt("closure::get_wrapper_for_bare_fn");
582 let arena = TypedArena::new();
583 let empty_param_substs = param_substs::empty();
584 let fcx = new_fn_ctxt(ccx, llfn, ast::DUMMY_NODE_ID, true, f.sig.output,
585 &empty_param_substs, None, &arena);
586 let bcx = init_function(&fcx, true, f.sig.output);
588 let args = create_datums_for_fn_args(&fcx,
589 ty::ty_fn_args(closure_ty)
591 let mut llargs = Vec::new();
592 match fcx.llretslotptr.get() {
594 assert!(!fcx.needs_ret_allocas);
595 llargs.push(llretptr);
599 llargs.extend(args.iter().map(|arg| arg.val));
601 let retval = Call(bcx, fn_ptr, llargs.as_slice(), None);
602 if type_is_zero_size(ccx, f.sig.output) || fcx.llretslotptr.get().is_some() {
608 // HACK(eddyb) finish_fn cannot be used here, we returned directly.
609 debuginfo::clear_source_location(&fcx);
615 pub fn make_closure_from_bare_fn<'blk, 'tcx>(bcx: Block<'blk, 'tcx>,
619 -> DatumBlock<'blk, 'tcx, Expr> {
620 let scratch = rvalue_scratch_datum(bcx, closure_ty, "__adjust");
621 let wrapper = get_wrapper_for_bare_fn(bcx.ccx(), closure_ty, def, fn_ptr, true);
622 fill_fn_pair(bcx, scratch.val, wrapper, C_null(Type::i8p(bcx.ccx())));
624 DatumBlock::new(bcx, scratch.to_expr_datum())