{"id":16564046,"url":"https://github.com/brndnmtthws/citrine","last_synced_at":"2025-03-21T11:32:53.866Z","repository":{"id":57483043,"uuid":"285456520","full_name":"brndnmtthws/citrine","owner":"brndnmtthws","description":"Elixir library for running cron-based scheduled jobs on your Erlang cluster","archived":false,"fork":false,"pushed_at":"2020-10-23T12:22:15.000Z","size":119,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-02T00:55:41.173Z","etag":null,"topics":["cron","cronjob","cronjob-scheduler","elixir","elixir-lang","elixir-library"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/citrine/readme.html","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brndnmtthws.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"brndnmtthws"}},"created_at":"2020-08-06T02:46:53.000Z","updated_at":"2024-04-24T12:51:50.000Z","dependencies_parsed_at":"2022-08-27T21:02:20.580Z","dependency_job_id":null,"html_url":"https://github.com/brndnmtthws/citrine","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brndnmtthws%2Fcitrine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brndnmtthws%2Fcitrine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brndnmtthws%2Fcitrine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brndnmtthws%2Fcitrine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brndnmtthws","download_url":"https://codeload.github.com/brndnmtthws/citrine/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221814973,"owners_count":16885086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cron","cronjob","cronjob-scheduler","elixir","elixir-lang","elixir-library"],"created_at":"2024-10-11T20:43:08.890Z","updated_at":"2024-10-28T10:05:11.505Z","avatar_url":"https://github.com/brndnmtthws.png","language":"Elixir","funding_links":["https://github.com/sponsors/brndnmtthws"],"categories":[],"sub_categories":[],"readme":"# [Citrine](http://hexdocs.pm/citrine/) [![Build/test](https://github.com/brndnmtthws/citrine/workflows/Build/test/badge.svg?branch=master)](https://github.com/brndnmtthws/citrine/actions?query=workflow%3ABuild%2Ftest+branch%3Amaster) [![Publish](https://github.com/brndnmtthws/citrine/workflows/Publish/badge.svg)](https://github.com/brndnmtthws/citrine/actions?query=workflow%3APublish+) [![Hex pm](http://img.shields.io/hexpm/v/citrine.svg?style=flat)](https://hex.pm/packages/citrine)\n\n_💎 Citrine energizes every level of life. It cleanses the chakras and opens the intuition. It's one of the most powerful energy crystals in the world. 💎_\n\nCitrine is a library for running scheduled jobs on an Erlang cluster, similar\nto cron. Citrine was created to satisfy a few simple requirements:\n\n* Provide reliable execution of jobs according to a schedule\n* Keep jobs running in the event of network splits or other failure scenarios\n* Build upon Elixir and Erlang primitives with minimum external dependencies\n* Be easy to operate and reason about\n* Work well in stateless container-based environments such as Kubernetes\n* Distribute jobs globally across a cluster\n* Follow a pattern of convention over configuration and minimize the number of knobs required\n\nInternally Citrine uses Erlang's excellent [mnesia\nmodule](https://erlang.org/doc/man/mnesia.html) for state and process\nmanagement. It uses in-memory tables, which comes with certain caveats.\n\nIf you're using mnesia elsewhere in your application, you should be aware that Citrine will attempt to join existing mnesia clusters.\n\n## What Citrine can and cannot do\n\nCitrine is not a perfect solution for all scheduling needs. There are certain features Citrine does not implement, or even try to implement, and if you require these features you should either look elsewhere or consider different patterns.\n\n* **Best effort**: There are some scenarios in which Citrine *could* potentially miss execution of a job, such as while rolling an update. Citrine will always try its best to execute jobs according to their schedules, but in some cases it may not.\n* **Exactly once semantics**: Citrine does not attempt to guarantee a job runs exactly once according to its schedule, it prefers to run a job multiple times in the event of failure scenarios such as netsplits.\n* **Interruption handling**: In the event a job is interrupted during execution, or the job itself fails, Citrine makes no attempt to restart or re-run the job.\n* **Idempotency**: This is not so much a limitation but rather a warning: your jobs should be designed to be idempotent to prevent strange side effects. Citrine cannot provide any guarantees.\n* **Clustering**: Citrine assumes you've already specified the cluster topology, either manually or using a library such as [libcluster](https://hexdocs.pm/libcluster/readme.html).\n\nIf you need stronger guarantees of execution, it's recommended that you\nuse a combination of a stateful queueing service with a worker library, such\nas [Exq](https://github.com/akira/exq).\n\nIf you're okay with the limitations of the library, Citrine is a great choice\nthanks to its simple interface, minimal dependencies and ease of operations.\n\n## Installation\n\nThe package can be installed by adding `citrine` to your list of dependencies\nin `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:citrine, \"~\u003e 0.1.0\"}\n  ]\nend\n```\n\n## Usage\n\nCreate a module for the core scheduler:\n\n```elixir\ndefmodule MyApp.Scheduler do\n  use Citrine.Scheduler, otp_app: :myapp\nend\n```\n\nAdd the scheduler to your supervisor tree, for example in `application.ex`:\n\n```elixir\ndefmodule MyApp.Application do\n  use Application\n  def start(_type, _args) do\n    children = [\n      # Start your Citrine scheduler\n      MyApp.Scheduler\n    ]\n    opts = [strategy: :one_for_one, name: MyApp.Supervisor]\n    Supervisor.start_link(children, opts)\n  end\nend\n```\n\nUse the scheduler to start and stop a job:\n\n```elixir\n# Create a job\njob = %Citrine.Job{\n  id: \"my_job_id\",\n  schedule: \"* * * * * *\", # Run every second\n  task: job_task,\n  extended_syntax: true # Use extended cron syntax\n}\n# Start or update a job\nMyApp.Scheduler.put_job(job)\n# Terminate and delete a job\nMyApp.Scheduler.delete_job(job)\n```\n\nFor further details, [see HexDocs](http://hexdocs.pm/citrine/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrndnmtthws%2Fcitrine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrndnmtthws%2Fcitrine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrndnmtthws%2Fcitrine/lists"}