4 - A API do ALua 6.0

• ALua
  • alua.create
  • alua.daemonid
  • alua.exit
  • alua.id
  • alua.link
  • alua.loop
  • alua.open
  • alua.send
  • alua.spawn
  • alua.tostring
    
• Tarefas
  • alua.task.schedule
• Temporizadores
  • alua.timer.create
  • alua.timer.cancel
  • alua.timer.flush

alua.create(config [, callback])

O que faz

Esta função cria um novo daemon, mas não conecta o processo ao mesmo.

Descrição

Esta função recebe como primeiro argumento (config) uma tabela de configuração que pode conter os seguintes campos:

Valor de retorno

Esta função operará de maneira assíncrona, assim, callback recebe como parâmetro uma tabela contendo informações sobre o resultado da operação, da seguinte forma:

Esta função também configura o valor dos campos alua.id e alua.daemonid.

Exemplo de uso

Para criar um daemon na porta 4821 de uma máquina com IP 192.168.21.67, usamos o seguinte código:

  function cb(reply)
     if reply.status == "ok" then
        print(reply.daemon)
        print(alua.id)
        print(alua.daemonid)
     else
        print(reply.error)
     end
  end

  alua.create( {addr = "192.168.21.67", port = 4821}, cb)

Voltar ao topo

alua.daemonid

Descrição

Este campo contém o identificador do daemon ao qual o processo está conectado. Caso o processo não esteja conectado, este campo contém nil.

Voltar ao topo

alua.exit([code])
alua.exit(procs [,code [, callback]])

O que faz

Finaliza o processo atual ou processo(s) remoto(s).

Descrição

Esta função pode ser usada de duas formas. Quando invocada sem parâmetros ou com um código inteiro (code) de finalização, esta função termina o processo que a invocou. O código de finalização é passado para a função os.exit().
Ex: alua.exit() ; alua.exit(1)

A segunda forma permite finalizar processos remotamente. procs pode ser um identificador de processo ou um array de identificadores. for o valor nil, o processo chamador é finalizado. Opcionalmente, pode ser informado um inteiro (code) que será usado como código de finalização. Caso seja fornecida, callback é uma função que é executada para obter o retorno da operação remota.

Valor de retorno

Não se tratando da terminação do processo chamador, esta função operará de maneira assíncrona, portanto no momento de envio da solicitação ao daemon nenhum valor será retornado. Quando a resposta for recebida, a função callback é chamada e terá como argumento uma tabela de resposta. Esta tabela tem como chaves os identificadores de cada processo cuja terminação foi solicitada, e o valor de cada chave é uma tabela contendo os campos descritos a seguir:

Exemplo de uso

Este primeiro exemplo cria um grupo de processos e em seguida os finaliza.

   require("alua")

   function exitcb(reply)
      for proc, termination in pairs(reply) do
         if termination.status == "ok" then
            print("Process " .. proc .. " terminated")
         end
     end
     -- Finaliza o daemon
     alua.exit(alua.daemonid, 0)
     -- Finaliza a própria execução
     alua.exit()
   end

   function spawncb(reply)
     -- Cria a lista de novos processos
     local procs = { }
     for proc in pairs(reply.processes) do
       table.insert(procs, proc)
     end
     -- Finaliza os novos processos
     alua.exit(procs, 0, exitcb)
   end

   function opencb(reply)
     -- Cria um conjunto de novos processos
     alua.spawn(4, spawncb)
   end

   alua.open({addr = "127.0.0.1", port = 6080}, opencb)
   alua.loop()   

Voltar ao topo

alua.id

Descrição

Este campo contém o identificador do processo atual, quando este está conectado a um daemon. Caso o processo não esteja conectado, este campo contém nil.

Voltar ao topo

alua.link(daemons [, callback])

O que faz

Faz o daemon do processo atual se conectar a outros daemons.

Descrição

Esta função recebe como argumento um array de identificadores de daemons a serem contactados (argumento daemons) ao daemon do processo requisitante, e tem como intuito montar a rede de daemons a serem utilizados pela aplicação. Em geral, a rede é montada na inicialização da aplicação. Processos em daemons diferentes só podem trocar mensagens se os seus daemons estiverem ligados.

Valor de retorno

Esta função opera de maneira assíncrona, portanto no momento de envio da solicitação ao daemon nenhum valor é retornado. Quando a resposta for recebida, a função callback é chamada e terá como argumento uma tabela de resposta, a qual poderá conter os seguintes campos:

Exemplo de uso

O código abaixo cria um daemon na porta 6080 e em seguinda cria e se conecta com um segundo daemon na porta 8061. Em seguida o processo realiza a ligação entre esses dois daemons. A função de callback apenas exibe o resultado da chamada de alua.link().

   require("alua")

   function linkcb(reply)
      for k, v in pairs(reply) do
         print(k, v)
      end
      print("---")
      for k, v in ipairs(reply.daemons) do
         print(k, v)
      end
   end

   function opencb(reply)
     alua.link({ "127.0.0.1:6080", "127.0.0.1:6081" }, linkcb)
   end

   alua.create({ addr = "127.0.0.1", port = 6080 })
   alua.open({ addr = "127.0.0.1", port = 6081 }, opencb)
   alua.loop()

Volta ao topo

alua.loop()

O que faz

Executa o loop de eventos do ALua.

Descrição

Esta função é responsável por verificar e disparar os eventos dos canais, tarefas e timers. Em geral, um programa ALua inicia sua execução com uma requisição de conexão a um daemon através de alua.open, e então invoca alua.loop para o tratamentos dos eventos subseqüentes.

Volta ao topo

alua.open(daemon [, callback])

O que faz

Conecta o processo em um daemon. Esta função pode opcionalmente criar o daemon.

Descrição

Esta função recebe como argumento o identificador de um daemon a ser contactado, ou, caso se queira criar um novo, uma tabela de configuração do novo daemon. O identificador de um daemon é uma string formada pelo endereço IPv4 da interface de rede, concatenado com ":" e então a porta de conexão.

A função alua.open também pode ser usada para criar um novo daemon e realizar a conexão com o mesmo. Neste caso, basta fornecer uma tabela de configuração em vez do identificador do daemon. Essa tabela de configuração é idêntica à descrita na função alua.create.

Valor de retorno

Esta função opera de maneira assíncrona, portanto no momento de envio da solicitação, valor é retornado. Quando a resposta for recebida, a função callback é chamada e terá como argumento uma tabela de resposta, a qual poderá conter os seguintes campos:

Exemplo de uso

Considere um daemon na porta 4821 de uma máquina com IP 192.168.21.67. O identificador do mesmo é, portanto, a string "192.168.21.67:4821", e para contactá-lo pode-se usar a seguinte chamada:

  function opencb(reply)
     for k, v in pairs(reply) do
        print(k, v)
     end
  end
  alua.open("192.168.21.67:4821", opencb)
  alua.loop()

Como um segundo exemplo, considere o código a seguir que cria um daemon na porta 5963 e IP "127.0.0.1" e em seguida se conecta com o mesmo.

  function opencb(reply)
    for k, v in pairs(reply) do
       print(k, v)
    end
  end
  alua.open({ addr = "127.0.0.1", port = 5963}, opencb)
  alua.loop()

Voltar ao topo

alua.send(destination, message [, callback])

O que faz

Envia uma mensagem para um ou mais processos.

Descrição

Esta função recebe destination como argumento, que pode ser o identificador de um processo ou um array de indetificadores, e envia a mensagem message a cada processo. Opcinalmente, a função callback pode ser informada para receber o resultado da requisição.

Valor de retorno

Esta função opera de maneira assíncrona, portanto no momento de envio da solicitação, nenhum valor é retornado. Quando a resposta for recebida e a função callback é chamada, tendo como argumento uma tabela de resposta. Esta tabela tem como chave o identificador de cada processo destinatário, e como valor uma tabela descrevendo o resultado, da seguinte forma:

Exemplo de uso

O exemplo a seguir cria 12 processos e então envia uma mensagem para dada um deles.

  require("alua") 

  function sendcb(reply)
      for id, msg in pairs(reply) do
        if msg.status == "ok" then
          print("Message received and executed by " .. id)
        else
          print("Process " .. id .. " could not receive or execute the message")
          print("Error: " .. msg.error)
        end
      end
   end

   function spawncb(reply)
      for proc, resp in pairs(reply.processes) do
         if resp.status == "ok" then
            alua.send(proc, [[ print("Hello World!") ]], sendcb)
         end
      end
   end

   function opencb(reply)
      alua.spawn(12, spawncb)
   end
   alua.open({addr = "127.0.0.1", port = 6080}, opencb)
   alua.loop()

Voltar ao topo

alua.spawn(param [, callback])

O que faz

Inicia novos processos.

Descrição

Esta função recebe como primeiro argumento um parâmetro especificando quantos processos devem ser criados, e, opcionalmente, uma função callback. O parâmetro param pode especificar: (i) a quantidade de processos a serem cridados; (ii) um array com os nomes dos novos processos; ou (iii) a forma como cada daemon deve criar os processos.

Se param for um número, a criação dos novos processos é distribuída entre os daemons participantes da aplicação, sempre tentando garantir o maior grau de simetria possível. Por exemplo, em uma aplicação com 4 daemons, a solicitação de 8 novos processos implica em cada daemon dando origem a 2 novos processos. Os novos processos são nomeados de acordo com seus respectivos daemons. Um processo criado em um daemon cujo identificador é "207.154.84.14:5921" terá como identificador uma string formada de um número que identifique unicamente o processo no daemon e pelo identificador do daemon. Por exemplo, processos criados no daemon "207.154.84.14:5921" podem ter como identificadores as strings "1@207.154.84.14:5921", "2@207.154.84.14:5921", "3@207.154.84.14:5921" e assim sucessivamente.

No caso de param ser um array, o mesmo deve conter os nomes dos processos a serem criados. Estes podem ser nomes arbitrários e serão os identificadores dos novos processos, e devem ser únicos de cada processo no universo da aplicação. Esses processos também serão distribuídos entre os daemons da aplicação.

Também é possível especificar como um cada determinado daemon criará os novos processos. Neste caso, a variável param deve ser uma tabela onde cada chave é o identificador de um daemon, e o valor pode ser um número ou um array de nomes. A chamada alua.spawn enviará para cada daemon a requisição apropriada, ou seja, criação de novos processos pela quantidade ou pelos nomes fornecidos.

Valor de retorno

Esta função opera de maneira assíncrona, portanto no momento de envio da solicitação ao daemon nenhum valor é retornado. Quando a resposta for recebida, a função callback é chamada, tendo como argumento uma tabela de resposta que segue o modelo descrito a seguir.

A tabela processes descrita acima, por sua vez, tem como chave os identificadores dos processos criados e como valor para cada chave, uma tabela contendo informações sobre o mesmo, descrita a seguir:

Exemplo de uso

O exemplo abaixo ilustra um uso típico da função alua.spawn.

  require("alua")

  function  spawncb(reply)
    for id, proc in pairs(reply.processes) do
      if proc.status == "ok" then
         print(id .. " successfully spawned on " .. proc.daemon)
      else
         print("Failed to spawn " .. id .. ": " .. proc.error)
      end
    end
  end

  function opencb(reply)
     alua.spawn(7, spawncb)
     alua.spawn({ "A", "B", "C", "D"}, spawncb)
  end

  alua.open({addr = "127.0.0.1";, port = 6080}, opencb)
  alua.loop()

Volta ao topo

alua.tostring(value)

O que faz

Serializa o objeto para string.

Descrição

Esta função fornece um mecanismo simples de serialização de valores Lua. Ela recebe como argumento um valor e retorna sua representação como string. No entanto, alua.tostring possui duas limitações: (i) não serializa funções, co-rotinas e userdata; (ii) não resolve referenças cruzadas em tabelas, ou seja, se duas chaves apontam para um mesmo valor, este será duplicado na serialização.

Valor de retorno

Esta função retorna uma string que representa o valor.

Volta ao topo

alua.task.schedule(func [, ...])

O que faz

Cria uma nova tarefa a ser executada no loop de eventos do ALua.

Descrição

alua.task.schedule registra a função func para ser executada uma vez dentro do loop de eventos. Após a execução, a função é removida do registro de tarefas. Qualquer valor fornecido além da função func é tido como seu argumento, e serão fornecidos no momento em que func for executada.

Voltar ao topo

alua.timer.create(freq, func)

O que faz

Cria um novo temporizador.

Descrição

Esta função registra a execução da função func (temporizador) com uma freqüência freq. A unidade da freqüência é em segundos e tem uma precisão de milisegundos.

Valor de retorno

Retorna um identificador para o temporizador.

Exemplo de uso

O exemplo a seguir cria dois temporizadores que exibem mensagens na tela.

   require("alua")
 
   function ping()
      print("ping")
   end
 
   function pong()
      print("pong")
   end
	 
   t1 = alua.timer.create(2, ping)
   t2 = alua.timer.create(3, pong)
 
   alua.loop()

Voltar ao topo

alua.timer.cancel(tp)

O que faz

Cancela a execução de um temporizador.

Descrição

Esta função remove o temporizador tp permanentemente do registro, fazendo com que o mesmo não seja mais disparado.

Exemplo de uso

O exemplo a seguir cria dois temporizadores, um temporizador para exibir uma mensagem a cada um segundo, e outro para cancelar os temporizadores (incluindo si mesmo).

   require("alua")
 
   function hello()
      print("Hello world!")
   end
 
   function stop()
      alua.timer.cancel(t1)
      alua.timer.cancel(t2)
   end
	 
   t1 = alua.timer.create(1, hello)
   t2 = alua.timer.create(10, stop)
 
   alua.loop()

Voltar ao topo

alua.timer.flush()

O que faz

Cancela todos os temporizadores.

Descrição

Esta função limpa o registro de temporizadores.

Exemplo de uso

O exemplo a seguir cria dois temporizadores, um temporizador para exibir uma mensagem a cada um segundo, e outro para cancelar os temporizadores (incluindo si mesmo).

   require("alua")
 
   function hello()
      print("Hello world!")
   end
 
   function stop()
      alua.timer.flush()
   end
	 
   t1 = alua.timer.create(1, hello)
   t2 = alua.timer.create(10, stop)
 
   alua.loop()

Voltar ao topo

Última atualização: 20-Mai-2008 16:28