GitLab

Briefly describe provided functionality instead of only referring to
https://golang.org/pkg/context and https://blog.golang.org/context.

e.g. Context -> PyContext, with_cancel -> pywith_cancel, etc. This will
make the followup transition of context to pyx/nogil more clear.

In preparation to start migrating, at least partially, context
functionality to nogil mode, first, similarly to package time (see
32f34607 "time: Move code to pyx"), move the code from context.py to
_context.pyx.

This is straight code movement + associated  setup.py & co adjusts.

We don't move just to context.pyx (note no _ prefix), since we will need
to continue distinguishing pyx/nogil from py objects/functions.

C.structZ is empty structure and chan[C.structZ] can be used in
pyx/nogil world. This way context tree initially created from Python can
be extended in pyx/nogil and e.g. root context can be canceled from
Python, which will correctly transfer the cancelation signal to pyx/nogil
world too.

In a followup commit we are going to add channel types (e.g. chan of
double, chan of int, etc) and accordingly there will be several nil
channel objects, e.g. nil(dtype=int), nil(dtype=double) etc, which will
be separate python objects. Even without data types, another planned
change is to add directional channels, e.g. a channel instance that can
only send, but not receive and vice versa(*).

This way for the same underlying channel object, there can be several
pychan objects that point to it - even for nil channel - e.g. nilchan
and `niltx = nilchan.txonly()` that creates another pychan object
pointing to the same underlying nil.

Since we want all channels (of the same type) that point to the same
underlying channel to compare as same, we cannot use "is" for comparison
and have to use ==. In other words channels, both at C and Python level,
should be perceived as pointers, of which there can be multiple ones
pointing to the same location, and thus == has to be used to compare
them.

(*) see https://golang.org/ref/spec#Channel_types for details.

Similarly to 78d85cdc (sync: threading.Event -> chan) replace everywhere
threaing.Lock usage with sync.Mutex . This brings 2 goods:

- sync.Mutex becomes more well tested;
- we untie ourselves from threading python module (threading.Lock was
  the last user).

Implement deadlines / timeouts using timers added recently in 9c260fde
(time: New package that mirrors Go's time).

We'll need to mark contexts that miss their deadline with
deadlineExceeded error in a follow-up patch.

In this patch: transform _BaseCtx._cancel to accept an error with which
a context has to be canceled, but for now always use canceled in places
where _cancel is called.

Same story as in Go, but we were lacking documentation notice about this.

- we are going to introduce golang.time, and from inside there without
  `from __future__ import absolute_imports` it won't be possible to import
  needed stdlib's time.

- we were already doing `from __future__ import print_function`, but
  only in some files.

-> It makes sense to apply updated __future__ usage uniformly.

Add .Context, .background .with_cancel and .with_value. There is no
support for deadline/timeout yet, since Go time package is not yet
mirrored.

Contrary to Go stdlib version, we also support context.merge that takes
https://godoc.org/lab.nexedi.com/kirr/go123/xcontext#hdr-Merging_contexts
for its inspiration.

See https://blog.golang.org/context for overview of contexts.