akruis
diff --git a/‎Doc/library/stackless/stackless.rst‎
Lines changed: 120 additions & 51 deletions b/‎Doc/library/stackless/stackless.rst‎
Lines changed: 120 additions & 51 deletions
diff --git a/‎Lib/stackless.py‎
Lines changed: 2 additions & 0 deletions b/‎Lib/stackless.py‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎Stackless/changelog.txt‎
Lines changed: 4 additions & 0 deletions b/‎Stackless/changelog.txt‎
Lines changed: 4 additions & 0 deletions
@@ -2,7 +2,7 @@
 ==================================================
 
 .. module:: stackless
-   :synopsis: Access the enhanced functionality provided by Stackless
+   :synopsis: Access the enhanced functionality provided by |SLP|
 
 .. moduleauthor:: Christian Tismer <tismer@stackless.com>
 .. sectionauthor:: Richard Tew <richard.m.tew@gmail.com>
@@ -21,6 +21,22 @@ the enhanced functionality provided by |SLP|.
    threads.rst
    pickling.rst
 
+---------
+Constants
+---------
+
+.. data:: PICKLEFLAGS_PRESERVE_TRACING_STATE
+
+   This constant defines an option flag for the function
+   :func:`pickle_flags`.
+
+   If this flag is set, a pickled tasklet contains
+   information about the tracing and/or profiling state of the tasklet.
+   Usually there's no need to set this flag.
+
+   .. versionadded:: 3.7
+
+
 ---------
 Functions
 ---------
@@ -42,36 +58,36 @@ The main scheduling related functions:
    The optional argument *timeout* is primarily used to run the scheduler
    in a different manner, providing pre-emptive scheduling.  A non-zero
    value indicates that as each tasklet is given a chance to run, it
-   should only be allowed to run as long as the number of 
-   :mod:`|PY| virtual instructions <dis>` are below this value. If a
+   should only be allowed to run as long as the number of
+   |PY| :mod:`virtual instructions <dis>` are below this value. If a
    tasklet hits this limit, then it is interrupted and the scheduler
    exits returning the now no longer scheduled tasklet to the caller.
-   
+
    Example - run until 1000 opcodes have been executed::
-   
+
        interrupted_tasklet = stackless.run(1000)
        # interrupted_tasklet is no longer scheduled, reschedule it.
        interrupted_tasklet.insert()
        # Now run your custom logic.
        ...
-       
-   The optional argument *threadblock* affects the way Stackless works when
+
+   The optional argument *threadblock* affects the way |SLP| works when
    channels are used for communication between threads.  Normally when
    the scheduler has no remaining tasklets to run besides the current one,
    the main tasklet is reawakened.  By engaging this option, if there are other
    running |PY| threads then the current one will instead block expecting
    them to eventually wake it up.
-   
+
    The optional argument *soft* affects how pre-emptive scheduling behaves.
    When a pre-emptive interruption would normally occur, instead of
    interrupting and returning the running tasklet, the scheduler exits at
    the next convenient scheduling moment.
-   
+
    The optional argument *ignore_nesting* affects the behaviour of the
    attribute :attr:`tasklet.nesting_level` on individual tasklets.  If set,
    interrupts are allowed at any interpreter nesting level, causing the
    tasklet-level attribute to be ignored.
-   
+
    The optional argument *totaltimeout* affects how pre-emptive scheduling
    behaves.  Normally the scheduler is interrupted when any given
    tasklet has been running for *timeout* instructions.  If a value is
@@ -87,7 +103,7 @@ The main scheduling related functions:
    inner application modifying the outer behaviour.
 
    .. note::
-   
+
       The most common use of this function is to call it either without
       arguments, or with a value for *timeout*.
 
@@ -96,20 +112,20 @@ The main scheduling related functions:
    Yield execution of the currently running tasklet.  When called, the tasklet
    is blocked and moved to the end of the chain of runnable tasklets.  The
    next tasklet in the chain is executed next.
-   
+
    If your application employs cooperative scheduling and you do not use
    custom yielding mechanisms built around channels, you will most likely
    call this in your tasklets.
 
    Example - typical usage of :func:`schedule`::
-   
+
        stackless.schedule()
-   
+
    As illustrated in the example, the typical use of this function ignores
    both the optional argument *retval* and the return value.  Note that as
    the variable name *retval* hints, the return value is the value of the
    optional argument.
-   
+
 .. function:: schedule_remove(retval=stackless.current)
 
    Yield execution of the currently running tasklet.  When called, the
@@ -120,15 +136,15 @@ The main scheduling related functions:
    build your own yielding primitive without using channels.  This is where
    the otherwise ignored optional argument *retval* and the return value
    are useful.
-   
+
    :attr:`tasklet.tempval` is used to store the value to be returned, and
    as expected, when this function is called it is set to *retval*.  Custom
    utility functions can take advantage of this and set a new value for
    :attr:`tasklet.tempval` before reinserting the tasklet back into the
    scheduler.
-   
+
    Example - a utility function::
-   
+
        def wait_for_result():
            waiting_tasklets.append(stackless.current)
            return stackless.schedule_remove()
@@ -157,59 +173,59 @@ Callback related functions:
    in *callable* being called.  Setting a value of ``None`` will result in the
    callback being disabled. The function returns the previous channel callback or
    ``None`` if none was installed.
-   
+
    Example - installing a callback::
-   
+
        def channel_cb(channel, tasklet, sending, willblock):
            pass
-           
+
        stackless.set_channel_callback(channel_cb)
 
    The *channel* callback argument is the channel on which the action is
    being performed.
-   
+
    The *tasklet* callback argument is the tasklet that is performing the
    action on *channel*.
 
    The *sending* callback argument is an integer, a non-zero value of which
    indicates that the channel action is a send rather than a receive.
-   
+
    The *willblock* callback argument is an integer, a non-zero value of which
    indicates that the channel action will result in *tasklet* being blocked
    on *channel*.
-   
+
 .. function:: get_channel_callback()
 
-   Get the current global channel callback. The function returns the 
+   Get the current global channel callback. The function returns the
    current channel callback or ``None`` if none was installed.
 
 .. function:: set_schedule_callback(callable)
 
    Install a callback for scheduling.  Every scheduling event, whether
    explicit or implicit, will result in *callable* being called. The function
    returns the previous channel callback or ``None`` if none was installed.
-   
+
    Example - installing a callback::
-   
+
        def schedule_cb(prev, next):
            pass
-           
+
        stackless.set_schedule_callback(callable)
-       
+
    The *prev* callback argument is the tasklet that was just running.
-   
+
    The *next* callback argument is the tasklet that is going to run now.
-   
+
    .. note::
-   
+
       During the execution of the scheduler callback the return value
-      of :func:`getcurrent` and the value of :attr:`current` are 
+      of :func:`getcurrent` and the value of :attr:`current` are
       implementation defined. You are not allowed to execute any methods, that
       change the state of stackless for the current thread.
 
 .. function:: get_schedule_callback()
 
-   Get the current global schedule callback. The function returns the 
+   Get the current global schedule callback. The function returns the
    current schedule callback or ``None`` if none was installed.
 
 Scheduler state introspection related functions:
@@ -218,19 +234,19 @@ Scheduler state introspection related functions:
 
    Return a tuple containing the threads main tasklet, current tasklet and
    run-count.
-   
+
    Example::
-   
+
        main_tasklet, current_tasklet, runcount = get_thread_info(thread_id)
 
 .. function:: getcurrent()
 
    Return the currently executing tasklet of this thread.
-   
+
 .. function:: getmain()
 
    Return the main tasklet of this thread.
-   
+
 .. function:: getruncount()
 
    Return the number of currently runnable tasklets.
@@ -250,23 +266,76 @@ Scheduler state introspection related functions:
        finally:
            stackless.switch_trap(-1)
 
+Pickling related functions:
+
+.. function:: pickle_flags_default(new_default=-1, mask=-1)
+
+   Get and set the per interpreter default value for pickle-flags.
+
+   A number of option flags control various aspects of |SLP| pickling behaviour.
+   See :func:`pickle_flags` for details.
+
+   Whenever |PY| initialises a thread state, it copies the default-value to
+   the thread state. Use function :func:`pickle_flags` to get and
+   set the flags of the current thread only.
+   
+   :param new_default: The new default value for pickle-flags
+   :type new_default: int
+   :param mask: A bit mask, that indicates the valid bits in argument "new_default"
+   :type mask: int
+   :return: the previous default value for pickle-flags
+   :rtype: int
+   :raises ValueError: if you try to set undefined bits
+
+   To inquire the value without changing it, omit the arguments (or set them to -1).
+
+   .. versionadded:: 3.7
+
+
+.. function:: pickle_flags(new_flags=-1, mask=-1)
+
+   Get and set per thread pickle-flags.
+
+   A number of option flags control various aspects of |SLP| pickling behaviour.
+   Symbolic names for the flags are supplied as module constants, which can be
+   :ref:`bitwise ORed <bitwise>` together and passed to this function.
+
+   Currently the following pickle option flags are defined:
+
+    - bit 0: :const:`PICKLEFLAGS_PRESERVE_TRACING_STATE`.
+
+   All other bits must be set to 0.
+
+   :param new_flags: The new value for pickle-flags of the current thread
+   :type new_flags: int
+   :param mask: A bit mask, that indicates the valid bits in argument "new_flags"
+   :type mask: int
+   :return: the previous value of pickle-flags of the current thread
+   :rtype: int
+   :raises ValueError: if you try to set undefined bits
+
+   To inquire the value without changing it, omit the arguments (or set them to -1).
+
+   .. versionadded:: 3.7
+
+
 Debugging related functions:
 
 .. function:: enable_softswitch(flag)
 
-   Control the switching behaviour. 
+   Control the switching behaviour.
    Tasklets can be either switched by moving C stack slices around
    or by avoiding stack changes at all. The latter is only possible
    in the top interpreter level. This flag exists once for the whole process.
    For inquiry only, use 'None' as the flag.
    By default, soft switching is enabled.
-   
+
    Example - safely disabling soft switching::
-   
+
        old_value = stackless.enable_softswitch(False)
        # Logic executed without soft switching.
        enable_softswitch(old_value)
-   
+
    .. note::
 
        Disabling soft switching in this manner is exposed for timing and
@@ -297,22 +366,22 @@ Attributes
    Example - usage::
 
        >>> stackless.runcount
-       1   
+       1
 
    .. note::
-   
+
        The minimum value of :attr:`runcount` will be ``1``, as the calling
        tasklet will be included.
 
    Equivalent function: :func:`getruncount`.
 
-   
+
 .. attribute:: threads
 
    A list of all thread ids, starting with the id of the main thread.
 
    Example - usage::
-   
+
        >>> stackless.threads
        [5148]
 
@@ -323,10 +392,10 @@ Attributes
    information about the tracing and/or profiling state of the tasklet.
    By default :attr:`pickle_with_tracing_state` is `False`. Usually
    there's no need to change this value.
-   
+
    If you need to set this attribute on a per thread base,
    you can redefine the attribute as a thread local property::
-   
+
       >>> import stackless
       >>> import threading
       >>> stackless._pickle_with_tracing = threading.local()
@@ -348,9 +417,9 @@ Exceptions
    This exception is used to silently kill a tasklet.  It should not be
    caught by your code, and along with other important exceptions like
    :exc:`SystemExit`, be propagated up to the scheduler.
-   
+
    The following use of the ``except`` clause should be avoided::
-   
+
        try:
            some_function()
        except:
@@ -360,7 +429,7 @@ Exceptions
    :exc:`TaskletExit`.  Unless you guarantee you actually raise the exceptions
    that should reach the scheduler, you are better to use ``except`` in the
    following manner::
-   
+
        try:
            some_function()
        except Exception:
 
@@ -21,6 +21,8 @@ def __reduce__():
 def __reduce_ex__(*args):
     return "stackless"
 
+PICKLEFLAGS_PRESERVE_TRACING_STATE = 1
+
 # Backwards support for unpickling older pickles, even from 2.7
 from _stackless import _wrap
 sys.modules["stackless._wrap"] = _wrap
 
@@ -9,6 +9,10 @@ What's New in Stackless 3.X.X?
 
 *Release date: 20XX-XX-XX*
 
+- https://github.com/stackless-dev/stackless/issues/139
+  New functions stackless.pickle_flags() and stackless.pickle_flags_default().
+  They can be used to control pickling of certain objects.
+
 - https://github.com/stackless-dev/stackless/issues/175
   Cleanup of the Stackless C-API: Including stackless_api.h in an extension
   module no longer defines internal stuff. Additionally I moved test code