diff options
| -rw-r--r-- | docs/faq.rst | 97 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/userguide.rst | 3 | ||||
| -rw-r--r-- | docs/versionhistory.rst | 1 |
4 files changed, 102 insertions, 0 deletions
diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000..cc32b08 --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,97 @@ +########################## +Frequently Asked Questions +########################## + +Why doesn't the scheduler run my jobs? +====================================== + +This could be caused by a number of things. The two most common issues are: + +#. Running the scheduler inside a uWSGI worker process while threads have not been enabled (see the + next section for this) +#. Running a :class:`~apscheduler.schedulers.background.BackgroundScheduler` and then letting the + execution reach the end of the script + +To demonstrate the latter case, a script like this will **not work**:: + + from apscheduler.schedulers.background import BackgroundScheduler + + def myjob(): + print('hello') + + scheduler = BackgroundScheduler() + scheduler.start() + scheduler.add_job(myjob, 'cron', hour=0) + +The script above will **exit** right after calling ``add_job()`` so the scheduler will not have a +chance to run the scheduled job. + +If you're having any other issue, then enabling debug logging as instructed in the +:ref:`troubleshooting` section should shed some light into the problem. + +How can I use APScheduler with uWSGI? +===================================== + +uWSGI employs some tricks which disable the Global Interpreter Lock and with it, the use of threads +which are vital to the operation of APScheduler. To fix this, you need to re-enable the GIL using +the ``--enable-threads`` switch. See the `uWSGI documentation <uWSGI-threads>`_ for more details. + +Also, assuming that you will run more than one worker process (as you typically would in +production), you should also read the next section. + +.. _uWSGI-threads: https://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html#a-note-on-python-threads + +How do I share a single job store among one or more worker processes? +===================================================================== + +Short answer: You can't. + +Long answer: Sharing a persistent job store among two or more processes will lead to incorrect +scheduler behavior like duplicate execution or the scheduler missing jobs, etc. This is because +APScheduler does not currently have any interprocess synchronization and signalling scheme that +would enable the scheduler to be notified when a job has been added, modified or removed from a job +store. + +Workaround: Run the scheduler in a dedicated process and connect to it via some sort of remote +access mechanism like RPyC_, gRPC_ or an HTTP server. The source repository contains an example_ of +a RPyC based service that is accessed by a client. + +.. _RPyC: https://rpyc.readthedocs.io/en/latest/ +.. _gRPC: https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=2ahUKEwj-wMe-1eLcAhXSbZoKHdzGDZsQFjAAegQICRAB&url=https%3A%2F%2Fgrpc.io%2F&usg=AOvVaw0Jt5Y0OKbHd8MdFt9Kc2FO +.. _example: https://github.com/agronholm/apscheduler/tree/master/examples/rpc + +How do I use APScheduler in a web application? +============================================== + +First read through the previous section. + +If you're running Django, you may want to check out django_apscheduler_. Note, however, that this +is a third party library and APScheduler developers are not responsible for it. + +Likewise, there is an unofficial extension called Flask-APScheduler_ which may or may not be useful +when running APScheduler with Flask. + +For Pyramid users, the pyramid_scheduler_ library may potentially be helpful. + +Other than that, you pretty much run APScheduler normally, usually using +:class:`~apscheduler.schedulers.background.BackgroundScheduler`. If you're running an asynchronous +web framework like aiohttp_, you probably want to use a different scheduler in order to take some +advantage of the asynchronous nature of the framework. + +Is there a graphical user interface for APScheduler? +==================================================== + +No graphical interface is provided by the library itself. However, there are some third party +implementations, but APScheduler developers are not responsible for them. Here is a potentially +incomplete list: + +* django_apscheduler_ +* apschedulerweb_ +* `Nextdoor scheduler`_ + +.. _django_apscheduler: https://pypi.org/project/django-apscheduler/ +.. _Flask-APScheduler: https://pypi.org/project/flask-apscheduler/ +.. _pyramid_scheduler: https://github.com/cadithealth/pyramid_scheduler +.. _aiohttp: https://pypi.org/project/aiohttp/ +.. _apschedulerweb: https://github.com/marwinxxii/apschedulerweb +.. _Nextdoor scheduler: https://github.com/Nextdoor/ndscheduler
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 81d42ed..1dd1c0f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,7 @@ Table of Contents migration contributing extending + faq Indices and tables diff --git a/docs/userguide.rst b/docs/userguide.rst index 22f865d..a1c147d 100644 --- a/docs/userguide.rst +++ b/docs/userguide.rst @@ -458,6 +458,8 @@ Example:: scheduler.add_listener(my_listener, EVENT_JOB_EXECUTED | EVENT_JOB_ERROR) +.. _troubleshooting: + Troubleshooting --------------- @@ -473,6 +475,7 @@ If you do not yet have logging enabled in the first place, you can do this:: This should provide lots of useful information about what's going on inside the scheduler. +Also make sure that you check the :doc:`faq` section to see if your problem already has a solution. Reporting bugs -------------- diff --git a/docs/versionhistory.rst b/docs/versionhistory.rst index b655d01..fc5f2d8 100644 --- a/docs/versionhistory.rst +++ b/docs/versionhistory.rst @@ -10,6 +10,7 @@ APScheduler, see the :doc:`migration section <migration>`. * Fixed scheduling of bound methods on persistent job stores (the workaround of scheduling ``YourClass.methodname`` along with an explicit ``self`` argument is no longer necessary as this is now done automatically for you) +* Added the FAQ section to the docs 3.5.1 |