"sched" --- Event scheduler
***************************

**Código-fonte:** Lib/sched.py

======================================================================

O módulo "sched" define uma classe que implementa um agendador de
eventos de uso geral:

class sched.scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

   A classe "scheduler" define uma interface genérica para agendar
   eventos. Ela precisa de duas funções para lidar com o "mundo
   externo" --- *timefunc* deve ser chamável sem argumentos e retornar
   um número (o "tempo", em quaisquer unidades). A função *delayfunc*
   deve ser chamável com um argumento, compatível com a saída de
   *timefunc*, e deve atrasar a mesma quantidade de unidades de tempo.
   *delayfunc* também será chamada com o argumento "0" após a execução
   de cada evento para permitir que outras threads executem em
   aplicações multithread.

   Alterado na versão 3.3: Os parâmetros *timefunc* e *delayfunc* são
   opcionais.

   Alterado na versão 3.3: A classe "scheduler" pode ser usada com
   segurança em ambientes multithread.

Exemplo:

   >>> import sched, time
   >>> s = sched.scheduler(time.time, time.sleep)
   >>> def print_time(a='default'):
   ...     print("From print_time", time.time(), a)
   ...
   >>> def print_some_times():
   ...     print(time.time())
   ...     s.enter(10, 1, print_time)
   ...     s.enter(5, 2, print_time, argument=('positional',))
   ...     # despite having higher priority, 'keyword' runs after 'positional' as enter() is relative
   ...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
   ...     s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",))
   ...     s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",))
   ...     s.run()
   ...     print(time.time())
   ...
   >>> print_some_times()
   1652342830.3640375
   From print_time 1652342830.3642538 second enterabs
   From print_time 1652342830.3643398 first enterabs
   From print_time 1652342835.3694863 positional
   From print_time 1652342835.3696074 keyword
   From print_time 1652342840.369612 default
   1652342840.3697174


Objetos Scheduler
=================

As instâncias "scheduler" têm os seguintes métodos e atributos:

scheduler.enterabs(time, priority, action, argument=(), kwargs={})

   Agenda um novo evento. O argumento *time* deve ser um tipo numérico
   compatível com o valor de retorno da função *timefunc* passada ao
   construtor. Eventos agendados para o mesmo *time* serão executados
   na ordem de sua prioridade *priority*. Um número menor representa
   uma prioridade maior.

   Executa o evento significa executar "action(*argument, **kwargs)".
   *argument* é uma sequência que contém os argumentos posicionais
   para *action*. *kwargs* é um dicionário que contém os argumentos
   nomeados para *action*.

   O valor de retorno é um evento que pode ser usado para cancelamento
   posterior do evento (veja "cancel()").

   Alterado na versão 3.3: o parâmetro *argument* é opcional.

   Alterado na versão 3.3: o parâmetro *kwargs* foi adicionado.

scheduler.enter(delay, priority, action, argument=(), kwargs={})

   Agenda um evento para atrasar *delay* mais unidades de tempo. Além
   do tempo relativo, os outros argumentos, o efeito e o valor de
   retorno são os mesmos de "enterabs()".

   Alterado na versão 3.3: o parâmetro *argument* é opcional.

   Alterado na versão 3.3: o parâmetro *kwargs* foi adicionado.

scheduler.cancel(event)

   Remove o evento da fila. Se *event* não for um evento atualmente na
   fila, este método levantará uma "ValueError".

scheduler.empty()

   Retorna "True" se a fila de eventos estiver vazia.

scheduler.run(blocking=True)

   Run all scheduled events. This method will wait  (using the
   "delayfunc()" function passed to the constructor) for the next
   event, then execute it and so on until there are no more scheduled
   events.

   Se *blocking* for falso, executa os eventos agendados que expirarão
   mais cedo (se houver) e então retorna o prazo da próxima chamada
   agendada no agendador (se houver).

   Tanto *action* quanto *delayfunc* podem levantar uma exceção. Em
   ambos os casos, o agendador manterá um estado consistente e
   propagará a exceção. Se uma exceção for gerada por *action*, o
   evento não será tentado em chamadas futuras para "run()".

   Se uma sequência de eventos demorar mais para ser executada do que
   o tempo disponível antes do próximo evento, o agendador
   simplesmente ficará para trás. Nenhum evento será descartado; o
   código de chamada é responsável por cancelar eventos que não são
   mais pertinentes.

   Alterado na versão 3.3: O argumento *blocking* foi adicionado.

scheduler.queue

   Atributo somente leitura que retorna uma lista de eventos futuros
   na ordem em que serão executados. Cada evento é exibido como uma
   *tupla nomeada* com os seguintes campos: time, priority, action,
   argument, kwargs.
