Periodic task system

What is Periodic?

Periodic is a Gearman like task system, provides a generic application framework to do the periodic work.

How Does Periodic work?

A Periodic powered application consists of three parts: a client, a worker, and a periodic server. The client is responsible for creating a job to be run and sending it to a periodic server. The periodic server will find a suitable worker that can run the job when then job time is up. The worker performs the work requested by the client and sends a stat to the periodic server. Periodic provides client and worker APIs that your applications call to talk with the periodic server (also known as periodicd) so you don’t need to deal with networking or mapping of jobs.

Internally, the periodic client and worker APIs communicate with the periodic server using TCP sockets. To explain how Periodic works in more detail, lets look at a simple application that will print a string on a random delay. The example is given in Haskell, although other APIs will look quite similar.

We start off by writing a client application that is responsible for sending off the job. It does this by using the Periodic client API to send some data associated with a function name, in this case the function random_print. The code for this is:

{-# LANGUAGE OverloadedStrings #-}

import Periodic.Client
clientEnv <- open "unix:///tmp/periodic.sock"
runClientM clientEnv $ submitJob "random_print" "Hello world!" Nothing Nothing

This code initializes a client class, configures it to use a periodic server with open, and then tells the client API to run the random_print function with the workload “Hello world!”. The function name and arguments are completely arbitrary as far as Periodic is concerned, so you could send any data structure that is appropriate for your application (text or binary). At this point the Periodic client API will package up the job into a Periodic protocol packet and send it to the periodic server to find an appropriate worker that can run the random_print function. Let’s now look at the worker code:

{-# LANGUAGE OverloadedStrings #-}
import Periodic.Worker
import Periodic.Job
import Control.Monad.IO.Class (liftIO)

startWorkerM "unix:///tmp/periodic/sock" $ do
  addFunc "random_print" $ do
    n <- name
    liftIO $ putStrLn h
    c <- count
    if c > 10 then workDone
              else schedLater' 5 1

  work 1

This code defines a function random_print that takes a string and print the string on a random delay for 10 times. It is used by a worker object to register a function named random_print after it is setup to connect to the same periodic server as the client. When the periodic server receives the job to be run, it looks at the list of workers who have registered the function name random_print and forwards the job on to one of the free workers. The Periodic worker API then takes this request, runs the function random_print, and sends the job stat of that function back to the periodic server.

As you can see, the client and worker APIs (along with the periodic server) deal with the job management and network communication so you can focus on the application parts.

Quick start

Install with stack

git clone https://github.com/Lupino/haskell-periodic.git
cd haskell-periodic

Install with stack

stack install

Static build with nix

make

Start periodic server

periodicd

Show file worker

{-# LANGUAGE OverloadedStrings #-}
module Main
  ( main
  ) where

import Periodic.Job (JobT, name, workDone)
import Periodic.Worker (addFunc, startWorkerM, work)
import Control.Monad.IO.Class (liftIO)

main :: IO ()
main = do
  startWorkerM "unix:///tmp/periodic.sock" $ do
    addFunc "show_file" showFile
    work 10

showFile :: JobM ()
showFile = do
  liftIO . putStrLn =<< name
  workDone

or use the periodic-run command

periodic-run show_file echo

or use the periodic-run-pipe command

periodic-run-pipe show_file sh -c "echo hello; cat"

Submit a job

periodic submit show_file abc.md

Show status

periodic status

MacOS bundle

make macos-bundle

# install
tar xvf macos-bundle.tar.bz2
./install.sh

Periodic clients

• node-periodic
• python-aio-periodic
• python-periodic
• haskell-periodic
• go-periodic
• write you owne client see protocol.