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);

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 : 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).