sl@0: /*=============================================================================
sl@0: Adaptable closures
sl@0:
sl@0: Phoenix V0.9
sl@0: Copyright (c) 2001-2002 Joel de Guzman
sl@0:
sl@0: Distributed under the Boost Software License, Version 1.0. (See
sl@0: accompanying file LICENSE_1_0.txt or copy at
sl@0: http://www.boost.org/LICENSE_1_0.txt)
sl@0:
sl@0: URL: http://spirit.sourceforge.net/
sl@0:
sl@0: ==============================================================================*/
sl@0: #ifndef PHOENIX_CLOSURES_HPP
sl@0: #define PHOENIX_CLOSURES_HPP
sl@0:
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: #include "boost/lambda/core.hpp"
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: namespace boost {
sl@0: namespace lambda {
sl@0:
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: //
sl@0: // Adaptable closures
sl@0: //
sl@0: // The framework will not be complete without some form of closures
sl@0: // support. Closures encapsulate a stack frame where local
sl@0: // variables are created upon entering a function and destructed
sl@0: // upon exiting. Closures provide an environment for local
sl@0: // variables to reside. Closures can hold heterogeneous types.
sl@0: //
sl@0: // Phoenix closures are true hardware stack based closures. At the
sl@0: // very least, closures enable true reentrancy in lambda functions.
sl@0: // A closure provides access to a function stack frame where local
sl@0: // variables reside. Modeled after Pascal nested stack frames,
sl@0: // closures can be nested just like nested functions where code in
sl@0: // inner closures may access local variables from in-scope outer
sl@0: // closures (accessing inner scopes from outer scopes is an error
sl@0: // and will cause a run-time assertion failure).
sl@0: //
sl@0: // There are three (3) interacting classes:
sl@0: //
sl@0: // 1) closure:
sl@0: //
sl@0: // At the point of declaration, a closure does not yet create a
sl@0: // stack frame nor instantiate any variables. A closure declaration
sl@0: // declares the types and names[note] of the local variables. The
sl@0: // closure class is meant to be subclassed. It is the
sl@0: // responsibility of a closure subclass to supply the names for
sl@0: // each of the local variable in the closure. Example:
sl@0: //
sl@0: // struct my_closure : closure<int, string, double> {
sl@0: //
sl@0: // member1 num; // names the 1st (int) local variable
sl@0: // member2 message; // names the 2nd (string) local variable
sl@0: // member3 real; // names the 3rd (double) local variable
sl@0: // };
sl@0: //
sl@0: // my_closure clos;
sl@0: //
sl@0: // Now that we have a closure 'clos', its local variables can be
sl@0: // accessed lazily using the dot notation. Each qualified local
sl@0: // variable can be used just like any primitive actor (see
sl@0: // primitives.hpp). Examples:
sl@0: //
sl@0: // clos.num = 30
sl@0: // clos.message = arg1
sl@0: // clos.real = clos.num * 1e6
sl@0: //
sl@0: // The examples above are lazily evaluated. As usual, these
sl@0: // expressions return composite actors that will be evaluated
sl@0: // through a second function call invocation (see operators.hpp).
sl@0: // Each of the members (clos.xxx) is an actor. As such, applying
sl@0: // the operator() will reveal its identity:
sl@0: //
sl@0: // clos.num() // will return the current value of clos.num
sl@0: //
sl@0: // *** [note] Acknowledgement: Juan Carlos Arevalo-Baeza (JCAB)
sl@0: // introduced and initilally implemented the closure member names
sl@0: // that uses the dot notation.
sl@0: //
sl@0: // 2) closure_member
sl@0: //
sl@0: // The named local variables of closure 'clos' above are actually
sl@0: // closure members. The closure_member class is an actor and
sl@0: // conforms to its conceptual interface. member1..memberN are
sl@0: // predefined typedefs that correspond to each of the listed types
sl@0: // in the closure template parameters.
sl@0: //
sl@0: // 3) closure_frame
sl@0: //
sl@0: // When a closure member is finally evaluated, it should refer to
sl@0: // an actual instance of the variable in the hardware stack.
sl@0: // Without doing so, the process is not complete and the evaluated
sl@0: // member will result to an assertion failure. Remember that the
sl@0: // closure is just a declaration. The local variables that a
sl@0: // closure refers to must still be instantiated.
sl@0: //
sl@0: // The closure_frame class does the actual instantiation of the
sl@0: // local variables and links these variables with the closure and
sl@0: // all its members. There can be multiple instances of
sl@0: // closure_frames typically situated in the stack inside a
sl@0: // function. Each closure_frame instance initiates a stack frame
sl@0: // with a new set of closure local variables. Example:
sl@0: //
sl@0: // void foo()
sl@0: // {
sl@0: // closure_frame<my_closure> frame(clos);
sl@0: // /* do something */
sl@0: // }
sl@0: //
sl@0: // where 'clos' is an instance of our closure 'my_closure' above.
sl@0: // Take note that the usage above precludes locally declared
sl@0: // classes. If my_closure is a locally declared type, we can still
sl@0: // use its self_type as a paramater to closure_frame:
sl@0: //
sl@0: // closure_frame<my_closure::self_type> frame(clos);
sl@0: //
sl@0: // Upon instantiation, the closure_frame links the local variables
sl@0: // to the closure. The previous link to another closure_frame
sl@0: // instance created before is saved. Upon destruction, the
sl@0: // closure_frame unlinks itself from the closure and relinks the
sl@0: // preceding closure_frame prior to this instance.
sl@0: //
sl@0: // The local variables in the closure 'clos' above is default
sl@0: // constructed in the stack inside function 'foo'. Once 'foo' is
sl@0: // exited, all of these local variables are destructed. In some
sl@0: // cases, default construction is not desirable and we need to
sl@0: // initialize the local closure variables with some values. This
sl@0: // can be done by passing in the initializers in a compatible
sl@0: // tuple. A compatible tuple is one with the same number of
sl@0: // elements as the destination and where each element from the
sl@0: // destination can be constructed from each corresponding element
sl@0: // in the source. Example:
sl@0: //
sl@0: // tuple<int, char const*, int> init(123, "Hello", 1000);
sl@0: // closure_frame<my_closure> frame(clos, init);
sl@0: //
sl@0: // Here now, our closure_frame's variables are initialized with
sl@0: // int: 123, char const*: "Hello" and int: 1000.
sl@0: //
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0:
sl@0:
sl@0:
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: //
sl@0: // closure_frame class
sl@0: //
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: template <typename ClosureT>
sl@0: class closure_frame : public ClosureT::tuple_t {
sl@0:
sl@0: public:
sl@0:
sl@0: closure_frame(ClosureT& clos)
sl@0: : ClosureT::tuple_t(), save(clos.frame), frame(clos.frame)
sl@0: { clos.frame = this; }
sl@0:
sl@0: template <typename TupleT>
sl@0: closure_frame(ClosureT& clos, TupleT const& init)
sl@0: : ClosureT::tuple_t(init), save(clos.frame), frame(clos.frame)
sl@0: { clos.frame = this; }
sl@0:
sl@0: ~closure_frame()
sl@0: { frame = save; }
sl@0:
sl@0: private:
sl@0:
sl@0: closure_frame(closure_frame const&); // no copy
sl@0: closure_frame& operator=(closure_frame const&); // no assign
sl@0:
sl@0: closure_frame* save;
sl@0: closure_frame*& frame;
sl@0: };
sl@0:
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: //
sl@0: // closure_member class
sl@0: //
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: template <int N, typename ClosureT>
sl@0: class closure_member {
sl@0:
sl@0: public:
sl@0:
sl@0: typedef typename ClosureT::tuple_t tuple_t;
sl@0:
sl@0: closure_member()
sl@0: : frame(ClosureT::closure_frame_ref()) {}
sl@0:
sl@0: template <typename TupleT>
sl@0: struct sig {
sl@0:
sl@0: typedef typename detail::tuple_element_as_reference<
sl@0: N, typename ClosureT::tuple_t
sl@0: >::type type;
sl@0: };
sl@0:
sl@0: template <class Ret, class A, class B, class C>
sl@0: // typename detail::tuple_element_as_reference
sl@0: // <N, typename ClosureT::tuple_t>::type
sl@0: Ret
sl@0: call(A&, B&, C&) const
sl@0: {
sl@0: assert(frame);
sl@0: return boost::tuples::get<N>(*frame);
sl@0: }
sl@0:
sl@0:
sl@0: private:
sl@0:
sl@0: typename ClosureT::closure_frame_t*& frame;
sl@0: };
sl@0:
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: //
sl@0: // closure class
sl@0: //
sl@0: ///////////////////////////////////////////////////////////////////////////////
sl@0: template <
sl@0: typename T0 = null_type,
sl@0: typename T1 = null_type,
sl@0: typename T2 = null_type,
sl@0: typename T3 = null_type,
sl@0: typename T4 = null_type
sl@0: >
sl@0: class closure {
sl@0:
sl@0: public:
sl@0:
sl@0: typedef tuple<T0, T1, T2, T3, T4> tuple_t;
sl@0: typedef closure<T0, T1, T2, T3, T4> self_t;
sl@0: typedef closure_frame<self_t> closure_frame_t;
sl@0:
sl@0: closure()
sl@0: : frame(0) { closure_frame_ref(&frame); }
sl@0: closure_frame_t& context() { assert(frame); return frame; }
sl@0: closure_frame_t const& context() const { assert(frame); return frame; }
sl@0:
sl@0: typedef lambda_functor<closure_member<0, self_t> > member1;
sl@0: typedef lambda_functor<closure_member<1, self_t> > member2;
sl@0: typedef lambda_functor<closure_member<2, self_t> > member3;
sl@0: typedef lambda_functor<closure_member<3, self_t> > member4;
sl@0: typedef lambda_functor<closure_member<4, self_t> > member5;
sl@0:
sl@0: private:
sl@0:
sl@0: closure(closure const&); // no copy
sl@0: closure& operator=(closure const&); // no assign
sl@0:
sl@0: template <int N, typename ClosureT>
sl@0: friend struct closure_member;
sl@0:
sl@0: template <typename ClosureT>
sl@0: friend class closure_frame;
sl@0:
sl@0: static closure_frame_t*&
sl@0: closure_frame_ref(closure_frame_t** frame_ = 0)
sl@0: {
sl@0: static closure_frame_t** frame = 0;
sl@0: if (frame_ != 0)
sl@0: frame = frame_;
sl@0: return *frame;
sl@0: }
sl@0:
sl@0: closure_frame_t* frame;
sl@0: };
sl@0:
sl@0: }}
sl@0: // namespace
sl@0:
sl@0: #endif