GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-110850: Add PyTime_t C API by encukou · Pull Request #115215 · python/cpython

Conversation

@encukou

@encukou encukou commented Feb 9, 2024 •
edited by github-actions Bot
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

This builds on Victor's PR: #112135

Additionally:

  • The API of the public functions now allows them to raise exceptions
  • The units of PyTime_t are now an implementation detail; PyTime_AsNanoseconds() is provided to convert to nanoseconds. (Currently, it's a no-op and always succeeds; the API allows reporting errors like overflow in the future.)
  • Issue: Please expose _PyTime_t, _PyTime_FromTimeval, and _PyTime_AsSecondsDouble as public APIs #110850

📚 Documentation preview 📚: https://cpython-previews--115215.org.readthedocs.build/

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
vstinner and others added 10 commits February 8, 2024 16:43
@vstinner @encukou
pythongh-110850: Add PyTime_t C API
4a8657c
Add PyTime_t API:

* PyTime_t type.
* PyTime_MIN and PyTime_MAX constants.
* PyTime_AsSecondsDouble(), PyTime_Monotonic(),
  PyTime_PerfCounter() and PyTime_GetSystemClock() functions.

Changes:

* Add Include/cpython/pytime.h header.
* Add Modules/_testcapi/time.c and Lib/test/test_capi/test_time.py
  tests on these new functions.
* Rename _PyTime_GetMonotonicClock() to PyTime_Monotonic().
* Rename _PyTime_GetPerfCounter() to PyTime_PerfCounter().
* Rename _PyTime_GetSystemClock() to PyTime_Time().
* Rename _PyTime_AsSecondsDouble() to PyTime_AsSecondsDouble().
* Rename _PyTime_MIN to PyTime_MIN.
* Rename _PyTime_MAX to PyTime_MAX.
@vstinner @encukou
Address Sam's review: update doc
3f60d67
@vstinner @encukou
Avoid reference to epoch_
a0c69bc
@encukou
Make the docs more concise & rename to "Clock C API"
8397a05
The `PyTime_` prefix is already used by datetime API, e.g. `PyDate_FromDate`.
@encukou
Doc: Make nanoseconds a detail; add PyTime_AsNanoseconds
793eb58
@encukou
Implement the fallible API and PyTime_AsNanoseconds
069eb79
@encukou
Use PY_INT64_T in the public header
744f53d
@encukou
Adjust What's New & News
38028a3
@encukou
Test PyTime_AsNanoseconds
74946d2
@encukou
Add (indirect) tests for PyTime_AsNanoseconds
8f7992e
@encukou
encukou requested review from a team, abalkin, pganssle and rhettinger as code owners February 9, 2024 13:21
@bedevere-app bedevere-app Bot added the awaiting core review label Feb 9, 2024
@bedevere-app bedevere-app Bot mentioned this pull request Feb 9, 2024
Please expose _PyTime_t, _PyTime_FromTimeval, and _PyTime_AsSecondsDouble as public APIs #110850
Closed
@encukou encukou mentioned this pull request Feb 9, 2024
gh-110850: Add PyTime C API (PyTime_t type) capi-workgroup/decisions#8
Closed
vstinner
vstinner reviewed Feb 9, 2024
View reviewed changes

@vstinner vstinner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is a first review.

I suggest to declare that PyTime_t is a number of nanoseconds and not add PyTime_AsNanoseconds().

There are some Sphinx warnings, like: c:identifier reference target not found: result in time.rst.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Doc/c-api/time.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/c-api/time.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/c-api/time.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/c-api/time.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Include/cpython/pytime.h Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Lib/test/test_capi/test_time.py Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Modules/_testcapi/time.c Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Modules/_testcapi/time.c Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Modules/_testcapi/time.c Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Python/pytime.c Resolved

Uh oh!

There was an error while loading. Please reload this page.

@vstinner

vstinner commented Feb 9, 2024

Copy link
Copy Markdown
Member

We should either:

  • Stick to 64-bit and nanoseconds.
  • Design the API so that the type can become 128-bit integer and use better resolution than nanoseconds. In this case, I suggest to add 2 functions: PyTime_AsNanoseconds() and PyTime_FromNanoseconds().
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

vstinner
vstinner reviewed Feb 9, 2024
View reviewed changes
Comment thread Doc/c-api/time.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

@vstinner

vstinner commented Feb 9, 2024

Copy link
Copy Markdown
Member

@encukou: Thanks for working on this PR!

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@rhettinger
rhettinger removed their request for review February 9, 2024 22:53
colesbury
colesbury reviewed Feb 10, 2024
View reviewed changes

@colesbury colesbury left a comment

Copy link
Copy Markdown
Contributor

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fallible APIs and generalization of PyTime_t makes these APIs harder to use without, it seems to me, sufficient benefit:

  • API users are likely to start relying on details, like the fact that PyTime_t is 64-bit time in nanoseconds. If we ever in the future wanted an API with a different precision or data type, we'd be better off introducing a new API than breaking users.
  • The underlying functions shouldn't fail on modern operating systems. Is there any OS we support that doesn't have CLOCK_MONOTONIC?

I commented below, but I don't think we can set+clear exceptions in the internal versions. They're used in contexts that don't have active PyThreadStates.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Python/pytime.c Resolved

Uh oh!

There was an error while loading. Please reload this page.

@colesbury

colesbury commented Feb 10, 2024

Copy link
Copy Markdown
Contributor

Oh, I see that fallible vs infallible API has already been extensively discussed in the C-API WG. The API doc should probably explicitly state that the functions require holding the GIL.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@Eclips4 Eclips4 added the topic-C-API label Feb 10, 2024
encukou added 5 commits February 12, 2024 12:33
@encukou
Remove PyTime_AsNanoseconds
ac94566
@encukou
Update docs to mention PyTime_t size and resolution, remove PyTime_As…
f4fc849
…Nanoseconds.
@encukou
Dedent docs for PyTime_MIN & MAX constants
3d43b73
@encukou
Use int64_t rather than PY_INT64_T
ba1c30b
@encukou
Add back full implementations of infallible functions
9fb5430
encukou added 6 commits February 12, 2024 13:28
@encukou
Add notes about the GIL
47f5d07
@encukou
Merge in the main branch
2b04579
@encukou
Remove PyTime_AsNanoseconds also from What's New & NEWS
7fad97d
@encukou
Note that PyTime_t is fixed now.
960c779
@encukou
Reorder the functions to reduce the diff
988340f
@encukou
Fix ReST warning
fbd801b
@vstinner

vstinner commented Feb 12, 2024

Copy link
Copy Markdown
Member

@colesbury:

Oh, I see that fallible vs infallible API has already been extensively discussed in the C-API WG. The API doc should probably explicitly state that the functions require holding the GIL.

That's the public C API. If Python needs variants which cannot fail, we can still have some in our internal C API.

Right, the rationale for reporting errors was discussed in length in the issue: capi-workgroup/decisions#8.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

vstinner
vstinner approved these changes Feb 12, 2024
View reviewed changes

@vstinner vstinner left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

For a few seconds (or many nanoseconds ;-)), I tried to imagine how the API and the implementation would look without PyTime_t type: using int64_t type. It's tempting to make the API as small as possible. IMO the API is better with a decided type, even if it's well documented that it's exactly int64_t. In terms of typing, it's better, it makes the code easier to follow, to review, etc.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

encukou reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
@bedevere-app bedevere-app Bot added awaiting merge and removed awaiting core review labels Feb 12, 2024
@encukou encukou mentioned this pull request Feb 12, 2024
gh-110850: Partially revert "gh-106316: Remove pytime.h header file (#106317) #115348
Closed
@encukou

encukou commented Feb 12, 2024

Copy link
Copy Markdown
Member Author

Yes: unlike int64_t, PyTime_t is always in nanoseconds.

vstinner reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner vstinner mentioned this pull request Feb 12, 2024
gh-110850: Add PyTime_t C API #112135
Closed
@encukou

encukou commented Feb 12, 2024

Copy link
Copy Markdown
Member Author

C API WG is in favour, so I'll merge.

vstinner reacted with hooray emoji vstinner reacted with heart emoji
All reactions
  • 🎉 1 reaction
  • ❤️ 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@encukou
encukou merged commit 879f454 into python:main Feb 12, 2024
@bedevere-app bedevere-app Bot removed the awaiting merge label Feb 12, 2024
@encukou
encukou deleted the fallible-pytime branch February 12, 2024 17:13
@encukou

encukou commented Feb 12, 2024

Copy link
Copy Markdown
Member Author

Thank you for the code & reviews!

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@vstinner

vstinner commented Feb 13, 2024

Copy link
Copy Markdown
Member

@encukou and me added a bare minimum public C API to read time with a PyTime_t type (64-bit signed number: nanoseconds): change commit 879f454.

typedef int64_t PyTime_t;
#define PyTime_MIN INT64_MIN
#define PyTime_MAX INT64_MAX

PyAPI_FUNC(double) PyTime_AsSecondsDouble(PyTime_t t);
PyAPI_FUNC(int) PyTime_Monotonic(PyTime_t *result);
PyAPI_FUNC(int) PyTime_PerfCounter(PyTime_t *result);
PyAPI_FUNC(int) PyTime_Time(PyTime_t *result);

If someone wants more functions to be exposed, please open a separated issue.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

fsc-eriker pushed a commit to fsc-eriker/cpython that referenced this pull request Feb 14, 2024
@encukou @vstinner @fsc-eriker
pythongh-110850: Add PyTime_t C API (pythonGH-115215)
daa6c27
* pythongh-110850: Add PyTime_t C API

Add PyTime_t API:

* PyTime_t type.
* PyTime_MIN and PyTime_MAX constants.
* PyTime_AsSecondsDouble(), PyTime_Monotonic(),
  PyTime_PerfCounter() and PyTime_GetSystemClock() functions.

Co-authored-by: Victor Stinner <[email protected]>
@vstinner vstinner mentioned this pull request Mar 5, 2024
gh-110850: Change PyTime C API error handling capi-workgroup/decisions#15
Closed
@scoder scoder mentioned this pull request May 7, 2024
Py3.13 support in cpython/time.pxd cython/cython#6187
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vstinner vstinner vstinner approved these changes
@colesbury colesbury colesbury left review comments
@pganssle pganssle Awaiting requested review from pganssle pganssle is a code owner
@abalkin abalkin Awaiting requested review from abalkin

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

topic-C-API

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

4 participants

@encukou @vstinner @colesbury @Eclips4
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.