AsyncTask

1. Overview

The AsyncTask module provides asynchronous subprocess execution for BastionGuard Backup. It provides the abstract task engine used to generate shell scripts, spawn child processes, stream standard output and error, expose progress, and control pause, resume, cancellation, and completion.

The file declares multiple related types that cooperate inside the same utility layer.

The implementation is written in Vala and uses GLib/GIO together with the application utility namespaces required by the file.

2. Dependencies and Integration

The module imports:

  • TeeJee.Logging
  • TeeJee.FileSystem
  • TeeJee.JsonHelper
  • TeeJee.ProcessHelper
  • TeeJee.System
  • TeeJee.Misc

Key runtime integrations include:

  • GIO/GLib streams – filesystem and process I/O

3. Declared Types

3.1 AsyncTask

public abstract class AsyncTask : GLib.Object

This class encapsulates the state and operations described by this source file.

3.2 AppStatus

public enum AppStatus

This enumeration defines the finite states or modes consumed by the module.

AppStatus contains:

NOT_STARTED
RUNNING
PAUSED
FINISHED
CANCELLED
PASSWORD_REQUIRED

4. State, Properties, Constants, and Signals

Public and protected state

  • public signal void stdout_line_read(string line); – Signal emitted to notify listeners when this event occurs.
  • public signal void stderr_line_read(string line); – Signal emitted to notify listeners when this event occurs.
  • public signal void task_complete(); – Signal emitted to notify listeners when this event occurs.
  • protected DataOutputStream dos_log – Session log output stream.
  • protected Pid child_pid – Process identifier used by the module.
  • protected string script_file – Filesystem-related value used for script file.
  • protected string working_dir – Filesystem-related value used for working dir.
  • public AppStatus status – Current lifecycle state of the task.
  • public GLib.Mutex status_line_mutex – Status value used to track status line mutex.
  • public int exit_code – Exit status returned by the child process.
  • public GLib.Timer timer – Timer used for elapsed-time and progress calculations.
  • public double progress – Normalized task progress value.
  • public double percent – Percentage parsed from command output.
  • public int64 prg_count – Current processed-item count.
  • public int64 prg_count_total – Expected total item count used for progress estimation.
  • public string status_line – Status value used to track status line.
  • public string stat_time_elapsed – Runtime state used by the module.
  • public string stat_time_remaining – Runtime state used by the module.

Internal state

  • private string err_line – Runtime state used by the module.
  • private string out_line – Runtime state used by the module.
  • private DataOutputStream dos_in – Runtime state used by the module.
  • private DataInputStream dis_out – Runtime state used by the module.
  • private DataInputStream dis_err – Runtime state used by the module.
  • private bool stdout_is_open – Boolean state controlling or reporting stdout open.
  • private bool stderr_is_open – Boolean state controlling or reporting stderr open.
  • private int input_fd – Runtime state used by the module.
  • private int output_fd – Runtime state used by the module.
  • private int error_fd – Runtime state used by the module.
  • private bool finish_called – Boolean state controlling or reporting finish called.
  • private string _status_line – Status value used to track status line.
  • private double timerOffset – Runtime state used by the module.
  • private double elapsed – Runtime state used by the module.

5. Public API and Operational Methods

5.1 AsyncTask()

protected AsyncTask()

Initializes the object state, allocates required collections or widgets, and applies constructor parameters.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.2 prepare()

public virtual void prepare()

Builds the task-specific shell script, logs it, and saves it inside the task working directory before execution.

5.3 begin()

protected virtual bool begin()

Marks the task as running, opens the generated script as a child process with pipes, and attaches asynchronous stdout, stderr, and child-watch callbacks.

  • Uses asynchronous callbacks, child watches, or worker-thread behavior.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.4 write_stdin()

public void write_stdin(string line)

Serializes and writes stdin to its configured destination.

  • Catches runtime errors locally and reports them through the logging layer or return value.

5.5 execute()

public virtual void execute()

Runs the preparation stage, starts the child process, initializes timing state, and ensures failed starts transition through the common completion path.

5.6 finish_task()

protected virtual void finish_task()

Implements the finish task operation for this module.

5.7 read_exit_code()

protected int read_exit_code()

Reads and parses exit code into the module data model.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.8 is_running()

public bool is_running()

Evaluates is running and returns a Boolean capability or state result.

5.9 stop()

public void stop(AppStatus status_to_update = AppStatus.CANCELLED)

Terminates the running child process and updates the task to the requested cancellation state.

5.10 pause()

public void pause(AppStatus status_to_update = AppStatus.PAUSED)

Sends the child process a stop signal, records elapsed time, and changes the task status to paused.

5.11 resume()

public void resume(AppStatus status_to_update = AppStatus.RUNNING)

Continues a paused child process, restarts timing, and changes the task status back to running.

5.12 print_app_status()

public void print_app_status()

Formats and emits diagnostic information for app status.

  • Processes credential-related values that should remain protected in memory and logs.

6. Internal Helpers

6.1 _get_status_line()

private string _get_status_line()

Implements the get status line operation for this module.

6.2 read_stdout()

private void read_stdout()

Reads and parses stdout into the module data model.

6.3 read_stderr()

private void read_stderr()

Reads and parses stderr into the module data model.

6.4 finish()

private void finish()

Implements the finish operation for this module.

7. Filesystem Paths and Resource Locations

The source references the following absolute or template paths:

/localhost/
/status

Some values are templates completed at runtime with application names, process IDs, device identifiers, or file names.

8. External Commands and System Interfaces

The module constructs, checks, or parses commands containing:

rsync -ai
script.sh

Execution success is determined from command exit status and, where applicable, parsed standard output or standard error.

9. Operational Flow

  1. Initialize object state, widgets, regular expressions, paths, or generated scripts.
  2. Read or discover source data and normalize it into the module data model.
  3. Apply the requested operation and update runtime or persistent state.
  4. Finalize the operation and release files, mounts, child processes, widgets, or cached state.

10. Error Handling and Diagnostics

  • GLib and filesystem exceptions are caught locally in the operations that can fail.
  • The TeeJee logging layer records errors, debug state, generated commands, and operational messages.

11. Runtime and Security Considerations

  • Dynamic command construction: caller-controlled values must be validated and escaped before being inserted into shell commands.
  • Sensitive data: credentials and passphrases should not be logged or persisted without protected storage and restrictive permissions.
  • Concurrency: callbacks and worker state must remain synchronized with object destruction and GTK main-loop ownership.

12. Licensing

The source is distributed under the GNU General Public License version 2 or any later version.

The source header identifies:

Copyright 2012-2018 Tony George <teejeetech@gmail.com>

Published on:
Last updated on: