Advertise sig_check() better in the developers manual

[jdemeyer]

Component: documentation

Author: Jeroen Demeyer

Branch/Commit: 3a21668

Reviewer: Vincent Delecroix, Dima Pasechnik

Issue created by migration from https://trac.sagemath.org/ticket/16902

[jdemeyer]

Branch: u/jdemeyer/ticket/16902

[jdemeyer]

Commit: 313d884

[jdemeyer]

New commits:

313d884

Improve sig_check() documentation

[videlec]

comment:3

1. sig_on/sig_off is Sage specific or is it included within Cython? It would be worth mentioning it. If it is Sage specific, why is that? and how do people coding in Cython do? (seems to be with nogil). If it is shipped with Cython, there should a pointer toward its documentation.

2. I am not sure that the following example is relevant.

def stack_sig_on():
    sig_on()
    sig_on()
    sig_on()
    # (some code)
    sig_off()
    sig_off()
    sig_off()

I mean, what would be the purpose of such code? If it is none, it is still interesting to mention it within a stack of calls like

def f1():
    sig_on()
    x = f2()
    sig_off()
    # ...

def f2():
    sig_on()
    # ...
    sig_off()
    return ans

3. The section Releasing the Global Interpreter Lock (GIL) was a bit obscure to me. It would be nice to have one sentence to say what it is. I guess it is related to my remark 1.

4. After reading the implementation of alarm I wonder why using alarm in doctests rather than directly the setitimer from the signal library? It is basically in TESTS blocks that such test
   would appear, and involving there the signal library is not ugly (and people reading it will learn about it instead of learning Sage wrapper!)

I learned many things reading it!
Thanks!
Vincent

[jdemeyer]

comment:4

Replying to @videlec:

1. sig_on/sig_off is Sage specific or is it included within Cython? It would be worth mentioning it. If it is Sage specific, why is that? and how do people coding in Cython do? (seems to be with nogil). If it is shipped with Cython, there should a pointer toward its documentation.

It is completely Sage-specific, I guess other people writing Cython code do not care about interrupts. There has been talking about putting these in Cython, but that has not happened yet.

2. If it is none, it is still interesting to mention it within a stack of calls like

def f1():
    sig_on()
    x = f2()
    sig_off()
    # ...

def f2():
    sig_on()
    # ...
    sig_off()
    return ans

Good suggestion!

3. The section Releasing the Global Interpreter Lock (GIL) was a bit obscure to me. It would be nice to have one sentence to say what it is. I guess it is related to my remark 1.

It is one of those things where, if you don't know it, you don't need to care. But I can put a link to the Cython documentation.

4. After reading the implementation of alarm I wonder why using alarm in doctests rather than directly the setitimer from the signal library?

Because alarm() is much cleaner.

It is basically in TESTS blocks that such test
would appear, and involving there the signal library is not ugly

Why is it not ugly?

and people reading it will learn about it instead of learning Sage wrapper!

If people care about Sage's wrapper, they can still figure out the implementation and can find out about setitimer that way.

[sagetrac-git]

Changed commit from 313d884 to 26a3edc

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

26a3edc

Further documentation fixes

[jdemeyer]

New commits:

26a3edc

Further documentation fixes

[videlec]

comment:7

Nothing more to say. You can set to positive review or ask another signal newbie to reread it!

Vincent

[jdemeyer]

Reviewer: Vincent Delecroix

[dimpase]

comment:9

my complaint about the change is about the line

or possibly the next Python code.

this is too vague (and grammatically weird - it should better be Python statement).

Does it mean that one need reach a Python exception? Or any Python statement?
And what is the role of the word possible there? I don't get it.

[jdemeyer]

comment:11

Replying to @dimpase:

it should better be Python statement.

I could change this.

Or any Python statement?
And what is the role of the word possible there? I don't get it.

I mean that Python code can sometimes raise a KeyboardInterrupt, but I also don't know exactly when this happens. For example, the following can be interrupted:

cython('while True: print "foo"')

But the following cannot be interrupted:

cython('while True: x = ["foo"] * 100')

[dimpase]

comment:12

Replying to @jdemeyer:

Replying to @dimpase:

it should better be Python statement.

I could change this.

yes please.

Or any Python statement?
And what is the role of the word possible there? I don't get it.

I mean that Python code can sometimes raise a KeyboardInterrupt, but I also don't know exactly when this happens. For example, the following can be interrupted:

cython('while True: print "foo"')

But the following cannot be interrupted:

cython('while True: x = ["foo"] * 100')

Do you mean to say that Python won't be able to catch the interrupt in the former case, but not in the latter case (i.e. the latter loop will keep running)?

[jdemeyer]

comment:13

Replying to @dimpase:

Replying to @jdemeyer:

Replying to @dimpase:

it should better be Python statement.

I could change this.

yes please.

Or any Python statement?
And what is the role of the word possible there? I don't get it.

I mean that Python code can sometimes raise a KeyboardInterrupt, but I also don't know exactly when this happens. For example, the following can be interrupted:

cython('while True: print "foo"')

But the following cannot be interrupted:

cython('while True: x = ["foo"] * 100')

Do you mean to say that Python won't be able to catch the interrupt in the former case, but not in the latter case (i.e. the latter loop will keep running)?

I mean that the loop in the last case will keep running because Python doesn't check for interrupts when executing x = ["foo"] * 100.

[dimpase]

comment:14

Replying to @jdemeyer:

Replying to @dimpase:

Replying to @jdemeyer:

Replying to @dimpase:

it should better be Python statement.

I could change this.

yes please.

Or any Python statement?
And what is the role of the word possible there? I don't get it.

I mean that Python code can sometimes raise a KeyboardInterrupt, but I also don't know exactly when this happens. For example, the following can be interrupted:

cython('while True: print "foo"')

But the following cannot be interrupted:

cython('while True: x = ["foo"] * 100')

Do you mean to say that Python won't be able to catch the interrupt in the former case, but not in the latter case (i.e. the latter loop will keep running)?

I mean that the loop in the last case will keep running because Python doesn't check for interrupts when executing x = ["foo"] * 100.

Whereas if the next statement after the latter was also cython, it would be terminated?
Is this what you mean by possibly?

[jdemeyer]

comment:15

Replying to @dimpase:

Whereas if the next statement after the latter was also cython, it would be terminated?

No, that's not what I mean. Pure Cython statements (which do not involve Python library calls) can never be interrupted.

[sagetrac-git]

Changed commit from 26a3edc to cae4023

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

cae4023

Clarify that Python can also interrupt

[dimpase]

Changed reviewer from Vincent Delecroix to Vincent Delecroix, Dima Pasechnik

[vbraun]

comment:19

File "src/doc/en/developer/coding_in_cython.rst", line 253, in doc.en.developer.coding_in_cython
Failed example:
    cython('print "Hello"')
Expected nothing
Got:
    Hello

[jdemeyer]

comment:20

Obviously :-)

[sagetrac-git]

Changed commit from cae4023 to 3a21668

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

3a21668

Fix silly doctest

[vbraun]

Changed branch from u/jdemeyer/ticket/16902 to 3a21668

[jdemeyer]

Built documentation

[jdemeyer]

Attachment: coding_in_cython.html.gz