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