Class MAETask
#include <MAETask.h >
MAETask is the class used to communicate with CommHub. It sends status and MAE platform commands (such as messages, RPC calls, database queries, global parameter queries). And it handles the responses and commands from CommHub.
SuperSocket sock |
to be used by friend classes, not app |
The constructor for MAETask so a MAE app can communicate and provide status with MAE.
Call this when the task immediately starts.
This moves the task into "Initializing" state.
You must set programName or call setName().
string msg |
the text of the log message (limited to 1000 characters long) |
Log any messages through this method; they are communicated to commhub, which logs them.
bool ok |
True if suspendable, False if not; default is True Default value: true |
Call this if your daemon is suspendable.
If it is not, it will never receive the TaskSuspend command.
Ask if we're currently suspended.
Return value: True if current setting is that the task/app can be suspended
This is a file descriptor for select() so the task
can monitor for control communication from CommHub.
Return value: a file system file descriptor
Return true when CommHub is using this class (commhub/MAETask.h returns true)
Return value: False for all tasks/apps except commhub.
const string& msg |
An informative message about the app's readiness. |
Call this when the task has finished initializing or to simply
report updated positive run status. Sends state 'ready' to CommHub.
const string& msg |
An informative message about the app's degraded state. |
Call this when the task realizes it is performing suboptimally.
Sends 'degraded' status to CommHub.
const string& msg |
An informative message about the app's failed state. |
Call this when the task has failed and cannot continue.
Sends 'failed' status to CommHub.
MAETaskCB cbfn |
static method or function to call, e.g. void exitNow(int n) |
Setup callback when CommHub sends Quit.
Default action: call exit(0).
MAETaskCB cbfn |
static method or function to call, e.g. void suspendNow(int n) |
Setup callback when CommHub sends Suspend.
Default is to ignore
MAETaskCB cbfn |
static method or function to call, e.g. void resumeNow(int n) |
Setup callback when CommHub sends Resume.
Default is to ignore
MAETaskCB cbfn |
static method or function to call, e.g. void toggleDebug(int n) |
Setup callback when commhub sends Debug.
Default action: toggle debug_on
Detach from parent process. This is unnecessary for single run tasks, but required for daemons.
bool forever |
true to continuously loop (default); false to process any outstanding requests Default value: true |
bool justone |
true to only process one event; false to process all (default) Default value: false |
Handle events in a loop from CommHub (forever) until Quit sent.
const string& msg |
An informative message about the app's degraded state. |
Call this when the task has completed successfully
int forcePid |
process id to report to CommHub Default value: 0 |
Call this after fork()ing to notify CommHub of our new pid.
bool wait |
true to wait for a command; false to only get a command already sent (default) Default value: false |
Call this routine when a control command was detected on the socket
const string& newname |
set the task's name |
If you want to change the name of this task, use this method.
Set the name before calling init() so CommHub knows who is contacting it (and sets up database/messaging permisisons.)
unsigned long newInstance |
the instance for this task Default value: 0 |
Set the instance id for this task. The first task with this name must register with 0; it is the base task.
Set the instance before calling init() so CommHub knows who is contacting it (and sets up database/messaging permisisons.)
Query the name of this task.
Return value: the name of the task/app
Query the instance of this task
Return value: the instance of the task/app; note that 0 is for the base app
Query if the current task is an instance (versus the base task)
Return value: true if the current task is an instance, false if base task
Query the task's name without its instance id.
Return value: the base task name
const string& taskName |
the task name to find the base name |
Extract a task's name without its instance id.
Return value: the base task name
const string& appid |
the id / message channel. |
Set the app id / messenge channel. Set this before calling init().
Query the app id / message channel in use.
Return value: the id / message channel
string newtype |
Future use. To change the application type of this task, use this method.
For now, the application type is the application name.
bool isManaged |
true if managed, false if not |
Configure if this task is managed by CommHub. (Default: no)
A managed task sends status to CommHub and responds to CommHub commands.
bool isDaemon |
true if daemon, false if not |
Configure if this task is a daemon. (Default: no)
A daemon talks to the CommHub and uses MAE services like messages, database, and RPC.
const string& name |
the name of the cluster or spoke where a task is running |
Deprecated. Configure if this task is part of a CommHub cluster or spoke, out and away from the root CommHub. (Default: no)
A cluster member is a thread inside a JVM; a spoke is a server separate from the root CommHub server.
Tasks/Apps can run on multiple hosts, but they require a local spoke CommHub for communication. A spoke
name is typically it's server's name, but that is not required. The cluster name is given by CommHub; it
is not for the app to decide.
Return the name of the CommHub cluster this app is connected to.
This is known after connecting to CommHub.
Return value: the name of the cluster. e.g. root or spoke name
Check if the current application is attached to the root CommHub.
Return value: true if app connected to root CommHub; false if sonnected to a spoke
const string& parameterName |
the name of the parameter |
string taskname |
the task that owns the parameter (default: this task) Default value: "" |
Query a CommHub system value for this task (not from data store).
In general, you should need to use this to query changeable defaults.
A daemon should not access the file system, but query from CommHub.
See commhub.ini file.
Return value: the value of the parameter (null string if no parameter found)
const string& parameterName |
the name of the parameter |
const string& parameterValue |
the new value for the parameter |
string taskname |
the task that owns the parameter (default: this task) Default value: "" |
Set a CommHub system value for this task (not in data store).
In general, you should need to use this to save global program settings that control behavior.
Return value: true if setting sent to CommHub
Get control CommHub command parameters. Most CommHub commands are just keywords, but if any arguments
follow the keyword, query them using this,
Return value: the parameters of the CommHub command
bool startIfNoAnswer |
if true, launch CommHub if CommHub not listening Default value: false |
const string& hostname |
the remote server name running CommHub - connect there Default value: "" |
Connect to CommHub (and start it if we can't connect)
Return value: true upon successfully connected to CommHub
const string& name |
the CommHub name for the task/daemon |
string& msg |
(output) the status of the CommHub started command |
Tell CommHub to start the named task/daemon.
This command will block until the instance has started (in Ready state) or failed.
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the CommHub name for the task/daemon |
unsigned long instanceId |
the non-0 instance to start |
Tell CommHub to start the named task/daemon as an instance.
This command will block until the instance has started (in Ready state) or failed.
The parent of the instance must be in the Ready state (not initializing) before an instance may be started. If attempted, the error "Invalid task" will be returned.
Return value: the status of the CommHub started command
const string& name |
the CommHub name for the task/daemon |
string& msg |
(output) the status of the CommHub started command |
Tell CommHub to stop the named daemon.
This command will block until the success or failure of stopping the named daemon is known.
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the CommHub name for the task/daemon |
string& msg |
(output) the status of the CommHub started command |
Tell CommHub to suspend the named daemon.
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the CommHub name for the task/daemon |
string& msg |
(output) the status of the CommHub started command |
Tell CommHub to resume the named daemon.
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the CommHub name for the task/daemon |
string& status |
(output) the status of the CommHub started command |
Get the named daemon's status.
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the CommHub name for the task/daemon |
string& status |
(output) the status of the CommHub started command if false returned; a comma separated list of instance ids if true returned |
Query all the active instance ids of the named task/daemon.
Return value: true if command sent and CommHub responded with a positive message
string status |
the msg string returned from the various control*() methods |
Given a status string from CommHub, get the current task/daemon status label, e.g. init, ready, degraded, etc.
Return value: the task status from the status line, e.g. NotRunning, Initializing, OK, Completed, Failed
string status |
the msg string returned from the various control*() methods |
Given a status string from CommHub, get the current task/daemon process id.
Return value: the task status from the status line
string status |
the msg string returned from the various control*() methods |
Given a status string from CommHub, get the current task/daemon cluster name / spoke name.
Return value: the task process id
string status |
the msg string returned from the various control*() methods |
Given a status string from CommHub, get the current task/daemon state.
Return value: the task state from the status line
string status |
the msg string returned from the various control*() methods |
Given a status string from CommHub, get the message portion.
Return value: the message
const string& name |
the task name |
string& msg |
(output) the status of the CommHub started command |
int level |
the debug level; -1 means toggle, 0 means off, 1 means shallow, 2 is deeper, etc. Default value: -1 |
Tell CommHub to toggle debug mode the named daemon
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the task name |
string& msg |
(output) the status of the CommHub started command |
Tell CommHub to tap messages to/from the named daemon with timestamps.
This can be handy for debugging or unit testing.
The app will write all those messages to log/ <name >.tap
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the task name |
string& msg |
(output) the status of the CommHub started command |
Tell CommHub a new task exists. Called by tadd after updating mgmttaskdb.csv with the new task.
Return value: true if command sent and CommHub responded with a positive message
const string& name |
the task name |
string& msg |
(output) the status of the CommHub started command |
Tell CommHub an old task is deleted. Called by tdel after removing the task from mgmttaskdb.csv.
Return value: true if command sent and CommHub responded with a positive message
CommHub's big STOP button. It forces CommHub to quit immediately. Use with caution!
Return value: true if command sent.
string& status |
(output) the status of the CommHub connections |
Ask CommHub for the status of all commhub connections; used by tstat command.
Output text formatted for human eyes.
Return value: true if command sent and CommHub responded with a positive message
const string& node |
the CommHub node name (spoke name or cluster name) to ask |
string& status |
(output) the status of the CommHub spokes |
Ask CommHub for the status of all known commhub spokes.
Return value: true if command sent and CommHub responded with a positive message
bool daemon |
true if current task is a daemon |
bool quitIfNoAnswer |
if true, exit with a message about unable to connect to CommHub Default value: true |
Engage commhub to make sure it's there and running.
Return value: true if command sent and CommHub responded with a positive message
time_t triggerTime |
the future time when the timer goes off |
Timer::TimerCB cbfn |
the method to call when the timer goes off |
void* data |
callback data to provide to the timer |
const string& triggerLabel |
the unique name of the timer (useful for tracking timers) |
Setup a one-time timer event for a specific time point in the future.
Return value: true if timer successfully setup
int delay |
the number of seconds in the future the timer should go off |
Timer::TimerCB cbfn |
the method to call when the timer goes off |
void* data |
callback data to provide to the timer |
const string& triggerLabel |
the unique name of the timer (useful for tracking timers) |
Setup a one-time timer event after a delay of specified seconds.
Return value: true if timer successfully setup
int seconds |
the number of seconds between repeating timer triggers |
Timer::TimerCB cbfn |
the method to call when the timer goes off |
void* data |
callback data to provide to the timer |
const string& triggerLabel |
the unique name of the timer (useful for tracking timers) |
Setup a time to trigger every so many seconds.
Return value: true if timer successfully setup
Query if a timer has been triggered.
Return value: true if a timer has been triggered and not serviced yet
Service all outstanding timers
Return value: the number of timers serviced
Get the list of future times in a HashArray.
The key is the triggerLabel, the value is the number of seconds to go before it triggers.
Return value: a HashArray with each trigger's time till it goes off
const string& triggerLabel |
the name of the setup timer to cancel |
Cancel a timer that was setup.
Return value: true if trigger cancelled, false if no such trigger setup
int _unused |
(ignored) Default value: 0 |
Toggle the socket tap that records all text going in/out.
Quit the task/daemon. Shuts the task/daemon down by calling the quit callback.
Suspend the daemon. Suspends the task/daemon by calling the suspend callback.
Resume the daemon. Resumes the task/daemon by calling the resume callback.
Get the directory with Configuration files
Return value: conf directory, e.g. /usr/mae/conf
Get the directory with log files
Return value: log directory, e.g. /usr/mae/log
string tasktype |
Is this daemon or task |
string taskname |
Label by which this task is known |
string cluster |
The name of the cluster/spoke we're in |
string appid |
Our application id |
unsigned long instance |
Root instance is 0, others are 1+ |
int commhubfd |
Connection back to CommHub |
bool managed |
Flag: does CommHub manage us? (Are we integrated?) Default: false |
bool daemon |
Flag: process is not oneshot; it stays running. Default: false |
int procid |
Our OS process id |
string cmdArgs |
args to control command from the OS |
bool saidHello |
Flag: Have we connected with CommHub yet? |
bool suspended |
Flag: Are we in suspend mode, which means the application is paused |
MAETaskCB quitCB |
Callbacks |
MAETaskCB debugCB |
Callbacks |
MAETaskCB tapCB |
Callbacks |
MAETaskCB suspendCB |
|
MAETaskCB resumeCB |
const string& msg |
|
const string& state |
|
const string& extra |
Default value: "" |
Send the status of this task to commhub
string cmd |
|
string& response |
Send a control command to commhub
const string& commhubHost |
Default value: "" |
Open the control channel with commhub
Return value: true upon success, false upon failure