camel-operation

camel-operation

Synopsis

                    CamelOperation;
void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                         const char *what,
                                                         int pc,
                                                         void *data);
enum                camel_operation_status_t;
CamelOperation *    camel_operation_new                 (CamelOperationStatusFunc status,
                                                         void *status_data);
void                camel_operation_mute                (CamelOperation *cc);
void                camel_operation_ref                 (CamelOperation *cc);
void                camel_operation_unref               (CamelOperation *cc);
void                camel_operation_cancel              (CamelOperation *cc);
void                camel_operation_uncancel            (CamelOperation *cc);
CamelOperation *    camel_operation_register            (CamelOperation *cc);
void                camel_operation_unregister          (CamelOperation *cc);
void                camel_operation_cancel_block        (CamelOperation *cc);
void                camel_operation_cancel_unblock      (CamelOperation *cc);
int                 camel_operation_cancel_check        (CamelOperation *cc);
int                 camel_operation_cancel_fd           (CamelOperation *cc);
struct PRFileDesc * camel_operation_cancel_prfd         (CamelOperation *cc);
CamelOperation *    camel_operation_registered          (void);
void                camel_operation_start               (CamelOperation *cc,
                                                         char *what,
                                                         ...);
void                camel_operation_start_transient     (CamelOperation *cc,
                                                         char *what,
                                                         ...);
void                camel_operation_progress            (CamelOperation *cc,
                                                         int pc);
void                camel_operation_progress_count      (CamelOperation *cc,
                                                         int sofar);
void                camel_operation_end                 (CamelOperation *cc);

Description

Details

CamelOperation

typedef struct _CamelOperation CamelOperation;


CamelOperationStatusFunc ()

void                (*CamelOperationStatusFunc)         (struct _CamelOperation *op,
                                                         const char *what,
                                                         int pc,
                                                         void *data);

op :

what :

pc :

data :


enum camel_operation_status_t

typedef enum _camel_operation_status_t {
	CAMEL_OPERATION_START = -1,
	CAMEL_OPERATION_END = -2
} camel_operation_status_t;


camel_operation_new ()

CamelOperation *    camel_operation_new                 (CamelOperationStatusFunc status,
                                                         void *status_data);

Create a new camel operation handle. Camel operation handles can be used in a multithreaded application (or a single operation handle can be used in a non threaded appliation) to cancel running operations and to obtain notification messages of the internal status of messages.

status :

Callback for receiving status messages. This will always be called with an internal lock held.

status_data :

User data.

Returns :

A new operation handle.

camel_operation_mute ()

void                camel_operation_mute                (CamelOperation *cc);

mutes a camel operation permanently. from this point on you will never receive operation updates, even if more are sent.

cc :


camel_operation_ref ()

void                camel_operation_ref                 (CamelOperation *cc);

Add a reference to the CamelOperation cc.

cc :

operation context

camel_operation_unref ()

void                camel_operation_unref               (CamelOperation *cc);

Unref and potentially free cc.

cc :

operation context

camel_operation_cancel ()

void                camel_operation_cancel              (CamelOperation *cc);

Cancel a given operation. If cc is NULL then all outstanding operations are cancelled.

cc :

operation context

camel_operation_uncancel ()

void                camel_operation_uncancel            (CamelOperation *cc);

Uncancel a cancelled operation. If cc is NULL then the current operation is uncancelled.

This is useful, if e.g. you need to do some cleaning up where a cancellation lying around in the same thread will abort any processing.

cc :

operation context

camel_operation_register ()

CamelOperation *    camel_operation_register            (CamelOperation *cc);

Register a thread or the main thread for cancellation through cc. If cc is NULL, then a new cancellation is created for this thread.

All calls to operation_register() should save their value and call operation_register again with that, to automatically stack registrations.

cc :

operation context

Returns :

the previously registered operatoin.

camel_operation_unregister ()

void                camel_operation_unregister          (CamelOperation *cc);

Unregister the current thread for all cancellations.

cc :

operation context

camel_operation_cancel_block ()

void                camel_operation_cancel_block        (CamelOperation *cc);

Block cancellation for this operation. If cc is NULL, then the current thread is blocked.

cc :

operation context

camel_operation_cancel_unblock ()

void                camel_operation_cancel_unblock      (CamelOperation *cc);

Unblock cancellation, when the unblock count reaches the block count, then this operation can be cancelled. If cc is NULL, then the current thread is unblocked.

cc :

operation context

camel_operation_cancel_check ()

int                 camel_operation_cancel_check        (CamelOperation *cc);

Check if cancellation has been applied to cc. If cc is NULL, then the CamelOperation registered for the current thread is used.

cc :

operation context

Returns :

TRUE if the operation has been cancelled.

camel_operation_cancel_fd ()

int                 camel_operation_cancel_fd           (CamelOperation *cc);

Retrieve a file descriptor that can be waited on (select, or poll) for read, to asynchronously detect cancellation.

cc :

operation context

Returns :

The fd, or -1 if cancellation is not available (blocked, or has not been registered for this thread).

camel_operation_cancel_prfd ()

struct PRFileDesc * camel_operation_cancel_prfd         (CamelOperation *cc);

Retrieve a file descriptor that can be waited on (select, or poll) for read, to asynchronously detect cancellation.

cc :

operation context

Returns :

The fd, or NULL if cancellation is not available (blocked, or has not been registered for this thread).

camel_operation_registered ()

CamelOperation *    camel_operation_registered          (void);

Returns :

the registered operation, or NULL if none registered.

camel_operation_start ()

void                camel_operation_start               (CamelOperation *cc,
                                                         char *what,
                                                         ...);

Report the start of an operation. All start operations should have similar end operations.

cc :

operation context

what :

action being performed (printf-style format string)

... :

varargs

camel_operation_start_transient ()

void                camel_operation_start_transient     (CamelOperation *cc,
                                                         char *what,
                                                         ...);

Start a transient event. We only update this to the display if it takes very long to process, and if we do, we then go back to the previous state when finished.

cc :

operation context

what :

printf-style format string describing the action being performed

... :

varargs

camel_operation_progress ()

void                camel_operation_progress            (CamelOperation *cc,
                                                         int pc);

Report progress on the current operation. If cc is NULL, then the currently registered operation is used. pc reports the current percentage of completion, which should be in the range of 0 to 100.

If the total percentage is not know, then use camel_operation_progress_count().

cc :

Operation to report to.

pc :

Percent complete, 0 to 100.

camel_operation_progress_count ()

void                camel_operation_progress_count      (CamelOperation *cc,
                                                         int sofar);

cc :

operation context

sofar :


camel_operation_end ()

void                camel_operation_end                 (CamelOperation *cc);

Report the end of an operation. If cc is NULL, then the currently registered operation is notified.

cc :

operation context