Move code EasyJobsBase.jl under EasyJobs.jl

EasyJobsBase/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 singularitti <[email protected]> and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

EasyJobsBase/Project.toml

@@ -0,0 +1,19 @@
+name = "EasyJobsBase"
+uuid = "db8ca866-b61f-4bd1-a9b9-75c107d645d4"
+authors = ["singularitti <[email protected]> and contributors"]
+version = "0.8.0"
+
+[deps]
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+Thinkers = "6d80a3f9-a943-41fa-97b3-3004c0daf7a3"
+UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[compat]
+Thinkers = "0.2"
+julia = "1"
+
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test"]

EasyJobsBase/README.md

@@ -0,0 +1,66 @@
+# EasyJobsBase
+
+|                                 **Documentation**                                  |                                                                                                 **Build Status**                                                                                                 |                                        **Others**                                         |
+| :--------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------: |
+| [![Stable][docs-stable-img]][docs-stable-url] [![Dev][docs-dev-img]][docs-dev-url] | [![Build Status][gha-img]][gha-url] [![Build Status][appveyor-img]][appveyor-url] [![Build Status][cirrus-img]][cirrus-url] [![pipeline status][gitlab-img]][gitlab-url] [![Coverage][codecov-img]][codecov-url] | [![GitHub license][license-img]][license-url] [![Code Style: Blue][style-img]][style-url] |
+
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://MineralsCloud.github.io/EasyJobsBase.jl/stable
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://MineralsCloud.github.io/EasyJobsBase.jl/dev
+[gha-img]: https://github.com/MineralsCloud/EasyJobsBase.jl/workflows/CI/badge.svg
+[gha-url]: https://github.com/MineralsCloud/EasyJobsBase.jl/actions
+[appveyor-img]: https://ci.appveyor.com/api/projects/status/github/MineralsCloud/EasyJobsBase.jl?svg=true
+[appveyor-url]: https://ci.appveyor.com/project/singularitti/EasyJobsBase-jl
+[cirrus-img]: https://api.cirrus-ci.com/github/MineralsCloud/EasyJobsBase.jl.svg
+[cirrus-url]: https://cirrus-ci.com/github/MineralsCloud/EasyJobsBase.jl
+[gitlab-img]: https://gitlab.com/singularitti/EasyJobsBase.jl/badges/main/pipeline.svg
+[gitlab-url]: https://gitlab.com/singularitti/EasyJobsBase.jl/-/pipelines
+[codecov-img]: https://codecov.io/gh/MineralsCloud/EasyJobsBase.jl/branch/main/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/MineralsCloud/EasyJobsBase.jl
+[license-img]: https://img.shields.io/github/license/MineralsCloud/EasyJobsBase.jl
+[license-url]: https://github.com/MineralsCloud/EasyJobsBase.jl/blob/main/LICENSE
+[style-img]: https://img.shields.io/badge/code%20style-blue-4495d1.svg
+[style-url]: https://github.com/invenia/BlueStyle
+
+The code is [hosted on GitHub](https://github.com/MineralsCloud/EasyJobsBase.jl),
+with some continuous integration services to test its validity.
+
+This repository is created and maintained by [@singularitti](https://github.com/singularitti).
+You are very welcome to contribute.
+
+## Installation
+
+The package can be installed with the Julia package manager.
+From the Julia REPL, type `]` to enter the Pkg REPL mode and run:
+
+```
+pkg> add EasyJobsBase
+```
+
+Or, equivalently, via the [`Pkg` API](https://pkgdocs.julialang.org/v1/getting-started/):
+
+```julia
+julia> import Pkg; Pkg.add("EasyJobsBase")
+```
+
+## Documentation
+
+- [**STABLE**][docs-stable-url] — **documentation of the most recently tagged version.**
+- [**DEV**][docs-dev-url] — _documentation of the in-development version._
+
+## Project status
+
+The package is tested against, and being developed for, Julia `1.6` and above on Linux,
+macOS, and Windows.
+
+## Questions and contributions
+
+You are welcome to post usage questions on [our discussion page][discussions-url].
+
+Contributions are very welcome, as are feature requests and suggestions. Please open an
+[issue][issues-url] if you encounter any problems. The [Contributing](@ref) page has
+guidelines that should be followed when opening pull requests and contributing code.
+
+[discussions-url]: https://github.com/MineralsCloud/EasyJobsBase.jl/discussions
+[issues-url]: https://github.com/MineralsCloud/EasyJobsBase.jl/issues

EasyJobsBase/src/EasyJobsBase.jl

@@ -0,0 +1,10 @@
+module EasyJobsBase
+
+include("jobs.jl")
+include("operations.jl")
+include("run.jl")
+include("status.jl")
+include("misc.jl")
+include("show.jl")
+
+end

EasyJobsBase/src/jobs.jl

@@ -0,0 +1,140 @@
+using Dates: DateTime, now
+using UUIDs: UUID, uuid1
+
+using Thinkers: Think
+
+export Job, WeaklyDependentJob, StronglyDependentJob
+
+@enum JobStatus begin
+    PENDING
+    RUNNING
+    SUCCEEDED
+    FAILED
+    INTERRUPTED
+end
+
+abstract type AbstractJob end
+# Reference: https://github.com/cihga39871/JobSchedulers.jl/blob/aca52de/src/jobs.jl#L35-L69
+"""
+    Job(core::Thunk; description="", username="")
+
+Create a simple job.
+
+# Arguments
+- `core`: a `Thunk` that encloses the job core definition.
+- `name`: give a short name to the job.
+- `description::String=""`: describe what the job does in more detail.
+- `username::String=""`: indicate who executes the job.
+
+# Examples
+```jldoctest
+julia> using Thinkers
+
+julia> a = Job(Thunk(sleep, 5); username="me", description="Sleep for 5 seconds");
+
+julia> b = Job(Thunk(run, `pwd` & `ls`); username="me", description="Run some commands");
+```
+"""
+mutable struct Job <: AbstractJob
+    id::UUID
+    core::Think
+    name::String
+    description::String
+    username::String
+    creation_time::DateTime
+    start_time::DateTime
+    end_time::DateTime
+    "Track the job status."
+    status::JobStatus
+    "Count hom many times the job has been run."
+    count::UInt64
+    "These jobs runs before the current job."
+    parents::Set{AbstractJob}
+    "These jobs runs after the current job."
+    children::Set{AbstractJob}
+    function Job(core::Think; name="", description="", username="")
+        return new(
+            uuid1(),
+            core,
+            name,
+            description,
+            username,
+            now(),
+            DateTime(0),
+            DateTime(0),
+            PENDING,
+            0,
+            Set(),
+            Set(),
+        )
+    end
+end
+abstract type DependentJob <: AbstractJob end
+mutable struct WeaklyDependentJob <: DependentJob
+    id::UUID
+    core::Think
+    name::String
+    description::String
+    username::String
+    creation_time::DateTime
+    start_time::DateTime
+    end_time::DateTime
+    "Track the job status."
+    status::JobStatus
+    "Count hom many times the job has been run."
+    count::UInt64
+    "These jobs runs before the current job."
+    parents::Set{AbstractJob}
+    "These jobs runs after the current job."
+    children::Set{AbstractJob}
+    function WeaklyDependentJob(core::Think; name="", description="", username="")
+        return new(
+            uuid1(),
+            core,
+            name,
+            description,
+            username,
+            now(),
+            DateTime(0),
+            DateTime(0),
+            PENDING,
+            0,
+            Set(),
+            Set(),
+        )
+    end
+end
+mutable struct StronglyDependentJob <: DependentJob
+    id::UUID
+    core::Think
+    name::String
+    description::String
+    username::String
+    creation_time::DateTime
+    start_time::DateTime
+    end_time::DateTime
+    "Track the job status."
+    status::JobStatus
+    "Count hom many times the job has been run."
+    count::UInt64
+    "These jobs runs before the current job."
+    parents::Set{AbstractJob}
+    "These jobs runs after the current job."
+    children::Set{AbstractJob}
+    function StronglyDependentJob(core::Think; name="", description="", username="")
+        return new(
+            uuid1(),
+            core,
+            name,
+            description,
+            username,
+            now(),
+            DateTime(0),
+            DateTime(0),
+            PENDING,
+            0,
+            Set(),
+            Set(),
+        )
+    end
+end

EasyJobsBase/src/misc.jl

@@ -0,0 +1,67 @@
+import Thinkers: getresult
+
+export countexecution,
+    descriptionof, creationtimeof, starttimeof, endtimeof, timecostof, getresult
+
+"""
+    countexecution(job::AbstractJob)
+
+Count how many times the `job` has been run.
+"""
+countexecution(job::AbstractJob) = Int(job.count)
+
+"""
+    descriptionof(job::AbstractJob)
+
+Return the description of the `job`.
+"""
+descriptionof(job::AbstractJob) = job.description
+
+"""
+    creationtimeof(job::AbstractJob)
+
+Return the creation time of the `job`.
+"""
+creationtimeof(job::AbstractJob) = job.creation_time
+
+"""
+    starttimeof(job::AbstractJob)
+
+Return the start time of the `job`. Return `nothing` if it is still pending.
+"""
+starttimeof(job::AbstractJob) = ispending(job) ? nothing : job.start_time
+
+"""
+    endtimeof(job::AbstractJob)
+
+Return the end time of the `job`. Return `nothing` if it has not exited.
+"""
+endtimeof(job::AbstractJob) = isexited(job) ? job.end_time : nothing
+
+"""
+    timecostof(job::AbstractJob)
+
+Return the time cost of the `job` since it started running.
+
+If `nothing`, the `job` is still pending. If it is finished, return how long it took to
+complete.
+"""
+function timecostof(job::AbstractJob)
+    if ispending(job)
+        return nothing
+    elseif isrunning(job)
+        return now() - job.start_time
+    else  # Exited
+        return job.end_time - job.start_time
+    end
+end
+
+"""
+    getresult(job::AbstractJob)
+
+Get the running result of the `job`.
+
+The result is wrapped by a `Some` type. Use `something` to retrieve its value.
+If it is `nothing`, the `job` is not finished.
+"""
+getresult(job::AbstractJob) = isexited(job) ? getresult(job.core) : nothing

EasyJobsBase/src/operations.jl

@@ -0,0 +1,54 @@
+export chain!, →, ←
+
+"""
+    chain!(x::AbstractJob, y::AbstractJob, z::AbstractJob...)
+
+Chain multiple `AbstractJob`s one after another.
+"""
+function chain!(x::AbstractJob, y::AbstractJob)
+    if x == y
+        throw(ArgumentError("a job cannot be followed by itself!"))
+    end
+    if y in x.children && x in y.parents
+        @info "You cannot chain the same jobs twice! No operations will be done!"
+    elseif y in x.children || x in y.parents  # This should never happen
+        error("Only one job is linked to the other, something is wrong!")
+    else
+        push!(x.children, y)
+        push!(y.parents, x)
+    end
+    return x
+end
+chain!(x::AbstractJob, y::AbstractJob, z::AbstractJob...) = foldr(chain!, (x, y, z...))
+"""
+    →(x, y)
+
+Chain two `AbstractJob`s.
+"""
+→(x::AbstractJob, y::AbstractJob) = chain!(x, y)
+"""
+    ←(y, x)
+
+Chain two `AbstractJob`s reversely.
+"""
+←(y::AbstractJob, x::AbstractJob) = x → y
+
+# See https://github.com/JuliaLang/julia/blob/70c873e/base/number.jl#L279-L280
+Base.iterate(x::AbstractJob) = (x, nothing)
+Base.iterate(::AbstractJob, ::Any) = nothing
+
+# See https://github.com/JuliaLang/julia/blob/70c873e/base/number.jl#L92
+Base.IteratorSize(::Type{<:AbstractJob}) = Base.HasShape{0}()
+
+# See https://github.com/JuliaLang/julia/blob/70c873e/base/number.jl#L84
+Base.eltype(::Type{T}) where {T<:AbstractJob} = T
+
+# See https://github.com/JuliaLang/julia/blob/70c873e/base/number.jl#L87
+Base.length(::AbstractJob) = 1
+
+# See https://github.com/JuliaLang/julia/blob/70c873e/base/number.jl#L80-L81
+Base.size(::AbstractJob) = ()
+Base.size(::AbstractJob, dim::Integer) = dim < 1 ? throw(BoundsError()) : 1
+
+# See https://github.com/JuliaLang/julia/blob/70c873e/base/number.jl#L282
+Base.in(x::AbstractJob, y::AbstractJob) = x == y