====================================
Contexts in ScotchPy
====================================

Contexts are implemented in ScotchPy with the Context class.

The Context class
#################



.. class:: Context(init=True)

    The graph constructor itself calls libscotch's ``contextAlloc`` function, and
    usually ``contextInit`` is called too.

    :param init:
        If True, the context allocation is followed by the init.
        If not, the :meth:`~Context.init` method needs to be called before.

    |

    .. method:: init()

        This routine Initializes the fields of the Context object instance.
        Called by a class constructor when ``init=True`` (by default).
        Mandatory before calling context routines or after calling :meth:`~Context.exit` in order to re-use the same Context instance.

    |

    .. method:: exit()

        This routine cleans-up all fields of the instance. Is the opposite of the :meth:`~Context.init` routine.
        Called automatically when the object is destroyed.
        Calling explicitly this method is only required when an :meth:`~Context.init` call follows.

    |

    .. method:: option_get_num(optinum, optival)


        This routine retrieves the value of a given integer context value of index ``optinum`` in ``optival``.

        :param optinum: The index of the context value to retrieve.
        :type optinum: Integer
        :param optival: The value of the context value.
        :type optival: Integer

    |

    .. method:: option_set_num(optinum, optival)

        This routine sets the value of a given integer context value of index ``optinum`` to ``optival``.

        :param optinum: The index of the context value to set.
        :type optinum: Integer
        :param optival: The value of the context value.
        :type optival: Integer

    |

    .. method:: random_clone()

        This routine clones the current state of the random number generator of the context.

    |

    .. method:: random_reset()

        This routine resets the state of the random number generator of the context.

    |

    .. method:: random_seed(seedval)

        This routine sets the state of the random number generator of the context with the given seed.

        :param seedval: The seed value.
        :type seedval: Integer

    |

    .. method:: thread_import1(thrdnbr)

        This routine initiates the capture, into the context, of an existing pool of threads. It must be called only by the master thread providing ``thrdnbr`` number of threads (including the master thread itself).

        :param thrdnbr: The number of threads to capture.
        :type thrdnbr: Integer

    |

    .. method:: thread_import2(thrdnum)

        This routine captures the ``thrdnum`` thread as a slave thread of the context. It must be called by each slave thread and the master thread after them. ``threading.Thread`` must be used here. See in "tests/test_context.py" for an example.

        :param thrdnum: The number of the thread to capture.
        :type thrdnum: Integer

    |

    .. method:: thread_spawn(thrdnbr, coretab)

        This routine populates the context with a pool of ``thrdnbr``- 1 slave threads, in addition to the master thread.

        :param thrdnbr: The number of threads to spawn.
        :type thrdnbr: Integer
        :param coretab: The core table, when not None, is an array of ``thrdnbr`` integers that gives the core number on which each thread should be bound.
        :type coretab: Any iterable of integers

    |

    .. method:: bind_graph(orggraf, cntgraf)

        This routine initializes a context container object with the graph ``orggraf``. The graph ``cntgraf`` is a context container that will contain the graph ``orggraf``. The graph ``orggraf`` is not duplicated, but only linked to the context container. The context container is used to store the graph and to provide a context for all graph operations.

        :param orggraf: The graph to bind.
        :type orggraf: :class:`~Graph`
        :param cntgraf: The context container.
        :type cntgraf: :class:`~Graph`

    |

    .. method:: bind_mesh(orgmesh, cntmesh)

        This routine initializes a context container object with the mesh ``orgmesh``. The mesh ``cntmesh`` is a context container that will contain the mesh ``orgmesh``. The mesh ``orgmesh`` is not duplicated, but only linked to the context container. The context container is used to store the mesh and to provide a context for all mesh operations.

        :param orgmesh: The mesh to bind.
        :type orgmesh: :class:`~Mesh`
        :param cntmesh: The context container.
        :type cntmesh: :class:`~Mesh`

    |

**Various functions are defined as wrappers of Context operations:**

    |

.. function:: context_alloc()

        This routine creates the ``contextAlloc`` function, returning a non-initialized
        :class:`Context` instance. It will need the :meth:`~Context.init` method to be
        called before the instance be built or loaded upon.

        |
