Canceling operations

Sometimes a user might want background job to stop, and Chronos gives developers such option.

How to reference a running operation

First of all, we need somehow show Chronos that it has to stop "that" operation launch. Each time Chronos starts running an operation, the run obtains a unique (within a single Android process) integer ID.

class MyActivity extends ChronosActivity{
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Button startButton = (Button) findViewById(R.id.button_start);
        startButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(final View v) {
                final int runId = runOperation(new MyOperation());
                Log.d("Chronos", "Launch id is " + runId);
            }
        });
    }
}

For instance, [tagged launches] (https://github.com/RedMadRobot/Chronos/wiki/Sinlge-launch-mode) would give you a same ID for later calls when the first is not over yet.

class MyActivity extends ChronosActivity{
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Button startButton = (Button) findViewById(R.id.button_start);
        startButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(final View v) {
                final int firstRunId = runOperation(new MyOperation(), "tag");
                Log.d("Chronos", "First launch id is " + firstRunId);
                final int secondRunId = runOperation(new MyOperation(), "tag");
                Log.d("Chronos", "Second launch id is " + secondRunId);
            }
        });
    }
}

Also, you may reference launch by its tag (if it is a tagged launch, of course). You'll see it later.

Canceling an operation

After we got a run ID, we can use it as a first parameter to cancel(int, boolean) method of ChronosConnector, or as a single parameter in cancelOperation(int) of pre-defined GUI classes.

class MyActivity extends ChronosActivity{

    private int mLastRunId;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        Button startButton = (Button) findViewById(R.id.button_start);
        startButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(final View v) {
                mLastRunId = runOperation(new MyOperation());
                Log.d("Chronos", "Launch id is " + mLastRunId);
            }
        });

        Button cancelButton = (Button) findViewById(R.id.button_cancel);
        cancelButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(final View v) {
                cancelOperation(mLastRunId); // Chronos would try to stop the run
            }
        });
    }
}

Can I be 100% sure operation is cancelled?

In short – no. But Chronos will do its best. However it is guaranteed, that you'll never see cancelled operation result in onOperationFinished() or in any onBroadcastOperationFinished().

Also there is a few things about stopping the operation execution, that you can find handy.

Interrupting

As you may noticed cancel(int, boolean) method of ChronosConnector has a second boolean parameter, which represents a permission to interrupt background threads. Set to true it will cause Chronos to interrupt a running thread, false will let the thread finish.

Cancellation effect

Both cancel(int, boolean) method of ChronosConnector, and cancelOperation(int) of pre-defined GUI classes returns boolean, that represents the effect of cancellation. If true is returned, Chronos either interrupted the running thread, or just marked the run as "cancelled", which would lead to no result delivery situation, no matter when and how will the actual run stop. If false is returned, Chronos didn't find a running operation with given ID, or there is something else, that prevents it from stopping the operation.

Cancellation tagger requests

If you want to cancel a [tagged request] (https://github.com/RedMadRobot/Chronos/wiki/Sinlge-launch-mode) you don't necessarily have to refer the launch via ID (however, you absolutely can), instead you can directly cancel the operation launch by tag, using cancel(String, boolean) method of ChronosConnector, or cancelOperation(String) of pre-defined GUI classes. The only difference here between canceling by tag and by ID is that in the first case cancel methods may return false, if there is no running operation with such tag at the moment.