SFXTask

Class for dealing with the task.

#include <SFXTask.h.hpp>

class SFXTask;

SFMTYPEDEFCLASS(SFXTask)

Collaboration diagram

Description

The SFXTask class is used to deal with a task, that is, callback that will be called in the next event loop. This class used mainly to implement cooperative multi-task processing.

The method to use the SFXTask class is as follows:

Set the timer information(callback function and data passed to the callback function) with the SFXTask::Set function.
Schedule the timer with the SFXTask::Schedule function, that is, register the callback into the AEE shell.
The callback will be called in the next event loop.
If the SFXTask::Cancel function is called before the callback is called, the scheduled task, the registered callback, will be canceled.

	Internal implementation
	The `SFXTask` class is implemented by using the `SFXCallback` class. In the internal implementaion, the `BREW API ISHELL_Resume` function is used to schedule a task, i.e., register a callback,

class MyClass {
private:
    SFXTimer _task; 
public:
    Void Function(Void);
    XALLBACK_DECLARE_SFXTASK(OnTask)
};

Void MyClass::Function(Void) 
{

    ...

    // set information necessary to schedule the task
    // * set the OnTask function and data passed to the OnTask function
    _task.Set(XALLBACK_INTERNAL(OnTask));

    /// schedule the task
    _task.Schedule();

    if (error != SFERR_NO_ERROR) {

        // if an error occurs: the OnTask function will not be called
    }
    
    // control is returned to BREW environment after this code ended,
    // the Ontask function will be called by BREW environment in the next event loop
}

/// callback function called by BREW environment in the next event loop
XALLBACK_IMPLEMENT_SFXTASK(MyClass, OnTask) 
{
    ...
}

Reference

BREW API ISHELL_Resume | SFXCallback | SFXTimer

Member

Constructor/Destructor
SFXTask( `Void` ) Constructor of the SFXTask class.
~SFXTask( `Void` ) Destructor of the SFXTask class.

Public Functions
`Void`	Cancel( `Void` ) Cancel the scheduled task.
static `SFXTaskConstRef`	EmptyInstance( `Void` ) Get the empty task.
`SFXCallback::CallbackSPP`	GetProcedure( `Void` ) Get the callback function set to this task.
`VoidPtr`	GetReference( `Void` ) Get the data passed to the callback function set to this task.
`Bool`	IsValid( `Void` ) Check whether or not the task is scheduled.
`SFCError`	Schedule( `Void` ) Schedule the task.
`Void`	Set( `SFXCallback::CallbackSPP` spp , `VoidPtr` reference ) Set information necessary to schedule the task.

SFXTask::SFXTask

Constructor of the SFXTask class.

[ public, explicit ]
SFXTask(Void);

Description

This constructor does nothing.

SFXTask::~SFXTask

Destructor of the SFXTask class.

[ public ]
~SFXTask(Void);

Description

This destructor cancels to schedule the task by calling the SFXTask::Cancel function internally.

Reference

SFXTask::Cancel | SFXTask::Schedule

SFXTask::Cancel

Cancel the scheduled task.

[ public ]
Void Cancel(Void);

Description

This function cancels the scheduled task, i.e., the registered callback.

The task scheduled with the SFXTask::Schedule function will be canceled. If no task is scheduled, nothing will happen.

	Tip
	When an application suspends, it is recommended to cancel the scheduled task with this function.

	Note
	This function is called in the `SFXTask::~SFXTask` destructor.

	Note
	Internally, this function calls the `SFXCallback::Cancel` function.

Reference

SFXTask::Schedule | SFXTask::~SFXTask | SFXCallback::Cancel

SFXTask::EmptyInstance

Get the empty task.

[ public, static ]
SFXTaskConstRef EmptyInstance(Void);

Return value

Empty SFXTask instance

Description

This function gets the instance that represents an empty task.

Reference

SFXTask::SFXTask

SFXTask::GetProcedure

Get the callback function set to this task.

[ public, const ]
SFXCallback::CallbackSPP GetProcedure(Void);

Return value

Callback function set to this task.

Description

This function gets the callback function set to this task with the SFXTask::Set function.

Note

	Note
Internally, this function calls the `SFXCallback::GetProcedure` function. Concretely, the value of the pfnNotify member of the `BREW API AEECallback` structure internally contained by this task will be returned.

Internally, this function calls the SFXCallback::GetProcedure function.

Concretely, the value of the pfnNotify member of the BREW API AEECallback structure internally contained by this task will be returned.

Reference

SFXTask::Set | SFXTask::GetReference | SFXCallback::GetProcedure | BREW API AEECallback

SFXTask::GetReference

Get the data passed to the callback function set to this task.

[ public, const ]
VoidPtr GetReference(Void);

Return value

Data passed to the callback function set to this task

Description

This function gets the data passed to the callback function set to this task with the SFXTask::Set function.

Note

	Note
Internally, this function calls the `SFXCallback::GetReference` function. Concretely, the value of the pNotifyData member of the `BREW API AEECallback` structure internally contained by this task will be returned.

Internally, this function calls the SFXCallback::GetReference function.

Concretely, the value of the pNotifyData member of the BREW API AEECallback structure internally contained by this task will be returned.

Reference

SFXTask::Set | SFXTask::GetProcedure | SFXCallback::GetReference | BREW API AEECallback

SFXTask::IsValid

Check whether or not the task is scheduled.

[ public, const ]
Bool IsValid(Void);

Return value

If scheduled: true
Otherwise: false

Description

This function whether or not the task is schedule with the SFXTask::Schedule function.

	Note
	Internally, this function calls the `SFXCallback::IsQueued` function.

Reference

SFXTask::Schedule | SFXCallback::IsQueued

SFXTask::Schedule

Schedule the task.

[ public ]
SFCError Schedule(Void);

Return value

If succeeds: SFERR_NO_ERROR
If failed to create the SFBShell instance internally: SFERR_FAILED

Description

This function schedules the task, i.e., registers the callback into the AEE shell.

If the task has already been scheduled, it will be canceled and scheduled again.

If this function is executed, the callback function set with the SFXTask::Set function will be called in the next event loop.

	Note
	Internally, after the task is canceled with the `SFXTask::Cancel` function, then it will be scheduled again with the `SFBShell::Resume` function.

	Prerequisite
	Before this function is called, it is necessary to set the task with the `SFXTask::Set` function.

Reference

SFXTask::Set | SFXTask::Cancel | SFXTask::IsValid | SFBShell | BREW API ISHELL_Resume

SFXTask::Set

Set information necessary to schedule the task.

[ public ]
Void Set(
    SFXCallback::CallbackSPP spp   // callback function
    VoidPtr reference              // data passed to the callback function
);

Description

This function sets information(callback function and data passed to it) necessary to schedule the task.

Internally, since the SFXTask::Cancel function is called first, the task that has been already scheduled before this function is called will be canceled.

	Note
	After this function is executed, schedule the task with the `SFXTask::Schedule` function (register the callback).

	Note
	This function internally calls the `SFXCallback::Set` function to set the callback function and the data passed to it specified in the arguments to the pfnNotify member and the pNotifyData member of the `BREW API AEECallback` structure internally contained by this task.

Reference