Módulo Time

O módulo time fornece funções para manipulação de tempo e datas. Este módulo é útil para scripts que precisam medir intervalos, aguardar por períodos específicos, parsear datas e implementar timeouts em operações assíncronas.

Características principais:

• Timestamps Unix em segundos

• Parse de datas no formato RFC 3339

• Sleep assíncrono não-bloqueante

• Timeouts para operações assíncronas

Funções Disponíveis

1. time.now()

Retorna o timestamp Unix atual em segundos.

Parâmetros:

• Nenhum

Retorno:

• número: Timestamp Unix atual (segundos desde 1 de Janeiro de 1970, 00:00:00 UTC)

Comportamento:

• Retorna o tempo atual em UTC

• Precisão de segundos (não milissegundos)

• Mesmo valor retornado por os.time() em Lua padrão

• Disponível como função global e no módulo time

Exemplo de Uso:

-- Usando o módulo time
local timestamp_modulo = time.now()
print("Timestamp módulo:", timestamp_modulo)

-- Usando a função global (mesma função)
local timestamp_global = now()
print("Timestamp global:", timestamp_global)

-- Ambos retornam o mesmo valor
print("São iguais?", timestamp_global == timestamp_modulo)  -- true

-- Calcular duração de operação
local inicio = time.now()
-- ... operação demorada ...
local fim = time.now()
local duracao = fim - inicio
print("Operação levou", duracao, "segundos")

-- Registrar eventos com timestamp
local evento = {
    tipo = "login",
    usuario = "admin",
    timestamp = now(),
    origem = system.hostname()
}

-- Agendar execução futura
local proxima_execucao = time.now() + 3600  -- 1 hora a partir de agora
print("Próxima execução em:", os.date("%H:%M:%S", proxima_execucao))

2. time.sleep(segundos)

Aguarda assincronamente por um número específico de segundos.

Parâmetros:

• segundos (número): Número de segundos para aguardar

Retorno:

• nil: A função não retorna valor (após a espera)

Comportamento:

• Precisão dependente do scheduler do sistema

Exemplo de Uso:

-- Aguardar 5 segundos
await(time.sleep(5))
print("5 segundos se passaram")

-- Implementar polling com intervalo
local function poll_com_intervalo(url, intervalo_segundos, max_tentativas)
    for tentativa = 1, max_tentativas do
        log.info("Tentativa", tentativa, "de", max_tentativas)

        -- Fazer requisição
        local resposta, status = http.get(url)

        if status == 200 then
            log.info("Sucesso na tentativa", tentativa)
            return resposta
        end

        -- Aguardar antes da próxima tentativa
        if tentativa < max_tentativas then
            log.info("Aguardando", intervalo_segundos, "segundos...")
            time.sleep(intervalo_segundos)
        end
    end

    log.error("Todas as tentativas falharam")
    return nil
end

-- Uso
local dados = poll_com_intervalo("https://api.exemplo.com/status", 10, 6)

-- Controle de execução com backoff exponencial
local function executar_com_backoff(funcao, max_tentativas)
    local tentativa = 1

    while tentativa <= max_tentativas do
        local ok, resultado = pcall(funcao)

        if ok then
            return resultado
        end

        -- Backoff exponencial: 2^(tentativa-1) segundos
        local wait_time = math.pow(2, tentativa - 1)
        log.warn("Tentativa", tentativa, "falhou. Aguardando", wait_time, "segundos")

        if tentativa < max_tentativas then
            time.sleep(wait_time)
        end

        tentativa = tentativa + 1
    end

    error("Todas as tentativas falharam")
end

3. time.parse(string_data)

Parseia uma string de data/hora no formato RFC 3339 e retorna um objeto de data.

Parâmetros:

• string_data (string): Data/hora no formato RFC 3339 (ex: “2024-01-15T10:30:00Z”)

Retorno:

• objeto LuaDateTime: Objeto com método seconds() que retorna timestamp Unix

Formato RFC 3339:

• YYYY-MM-DDTHH:MM:SSZ (UTC)

• YYYY-MM-DDTHH:MM:SS+HH:MM (com offset de fuso horário)

• Exemplos: “2024-01-15T10:30:00Z”, “2024-01-15T07:30:00-03:00”

Exemplo de Uso:

-- Parsear data UTC
local data_utc = time.parse("2024-01-15T10:30:00Z")
local timestamp_utc = data_utc:seconds()
print("Timestamp UTC:", timestamp_utc)  -- 1705314600

-- Parsear data com offset de fuso
local data_local = time.parse("2024-01-15T07:30:00-03:00")
local timestamp_local = data_local:seconds()
print("Timestamp local:", timestamp_local)  -- 1705314600 (mesmo momento)

-- Converter para formato legível
local function formatar_data_rfc3339(timestamp)
    return os.date("%Y-%m-%dT%H:%M:%SZ", timestamp)
end

-- Calcular diferença entre datas
local data1 = time.parse("2024-01-15T10:30:00Z")
local data2 = time.parse("2024-01-15T11:45:00Z")
local diferenca = data2:seconds() - data1:seconds()
print("Diferença:", diferenca, "segundos (", diferenca/60, "minutos)")

-- Validar e parsear data de entrada
local function parsear_data_segura(data_string)
    local ok, data = pcall(time.parse, data_string)
    if ok then
        return data:seconds()
    else
        log.error("Data inválida:", data_string, "-", data)
        return nil
    end
end

-- Uso
local timestamp = parsear_data_segura("2024-01-15T10:30:00Z")
if timestamp then
    print("Data válida:", os.date("%d/%m/%Y %H:%M:%S", timestamp))
end