.TH "Globus Callback Spaces" 3 "Sat Nov 8 2014" "Version 15.26" "globus_common" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Globus Callback Spaces \- 
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBGLOBUS_CALLBACK_GLOBAL_SPACE\fP"
.br
.RI "\fIGlobal callback space\&. \fP"
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBglobus_callback_space_behavior_t\fP { \fBGLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE\fP, \fBGLOBUS_CALLBACK_SPACE_BEHAVIOR_SERIALIZED\fP, \fBGLOBUS_CALLBACK_SPACE_BEHAVIOR_THREADED\fP }"
.br
.RI "\fICallback space behaviors describe how a space behaves\&. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_init\fP (\fBglobus_callback_space_t\fP *space, \fBglobus_callback_space_attr_t\fP attr)"
.br
.RI "\fIInitialize a user space\&. \fP"
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_reference\fP (\fBglobus_callback_space_t\fP space)"
.br
.RI "\fITake a reference to a space\&. \fP"
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_destroy\fP (\fBglobus_callback_space_t\fP space)"
.br
.RI "\fIDestroy a reference to a user space\&. \fP"
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_attr_init\fP (\fBglobus_callback_space_attr_t\fP *attr)"
.br
.RI "\fIInitialize a space attr\&. \fP"
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_attr_destroy\fP (\fBglobus_callback_space_attr_t\fP attr)"
.br
.RI "\fIDestroy a space attr\&. \fP"
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_attr_set_behavior\fP (\fBglobus_callback_space_attr_t\fP attr, \fBglobus_callback_space_behavior_t\fP behavior)"
.br
.RI "\fISet the behavior of a space\&. \fP"
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_attr_get_behavior\fP (\fBglobus_callback_space_attr_t\fP attr, \fBglobus_callback_space_behavior_t\fP *behavior)"
.br
.RI "\fIGet the behavior associated with an attr\&. \fP"
.ti -1c
.RI "\fBglobus_result_t\fP \fBglobus_callback_space_get\fP (\fBglobus_callback_space_t\fP *space)"
.br
.RI "\fIRetrieve the space of a currently running callback\&. \fP"
.ti -1c
.RI "int \fBglobus_callback_space_get_depth\fP (\fBglobus_callback_space_t\fP space)"
.br
.RI "\fIRetrieve the current nesting level of a space\&. \fP"
.ti -1c
.RI "\fBglobus_bool_t\fP \fBglobus_callback_space_is_single\fP (\fBglobus_callback_space_t\fP space)"
.br
.RI "\fISee if the specified space is a single threaded behavior space\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 

.SH "Macro Definition Documentation"
.PP 
.SS "#define GLOBUS_CALLBACK_GLOBAL_SPACE"

.PP
Global callback space\&. The 'global' space handle\&.
.PP
This is the default space handle implied if no spaces are explicitly created\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBglobus_callback_space_behavior_t\fP"

.PP
Callback space behaviors describe how a space behaves\&. In a non-threaded build all spaces exhibit a behavior == _BEHAVIOR_SINGLE\&. Setting a specific behavior in this case is ignored\&.
.PP
In a threaded build, _BEHAVIOR_SINGLE retains all the rules and behaviors of a non-threaded build while _BEHAVIOR_THREADED makes the space act as the global space\&.
.PP
Setting a space's behavior to _BEHAVIOR_SINGLE guarantees that the poll protection will always be there and all callbacks are serialized and only kicked out when polled for\&. In a threaded build, it is still necessary to poll for callbacks in a _BEHAVIOR_SINGLE space\&. (\fBglobus_cond_wait()\fP will take care of this for you also)
.PP
Setting a space's behavior to _BEHAVIOR_SERIALIZED guarantees that the poll protection will always be there and all callbacks are serialized\&. In a threaded build, it is NOT necessary to poll for callbacks in a _BEHAVIOR_SERIALIZED space\&. Callbacks in this space will be delivered as soon as possible, but only one outstanding (and unblocked) callback will be allowed at any time\&.
.PP
Setting a space's behavior to _BEHAVIOR_THREADED allows the user to have the poll protection provided by spaces when built non-threaded, yet, be fully threaded when built threaded (where poll protection is not needed) 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIGLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE \fP\fP
The default behavior\&. Indicates that you always want poll protection and single threaded behavior (callbacks need to be explicitly polled for 
.TP
\fB\fIGLOBUS_CALLBACK_SPACE_BEHAVIOR_SERIALIZED \fP\fP
Indicates that you want poll protection and all callbacks to be serialized (but they do not need to be polled for in a threaded build) 
.TP
\fB\fIGLOBUS_CALLBACK_SPACE_BEHAVIOR_THREADED \fP\fP
Indicates that you only want poll protection 
.SH "Function Documentation"
.PP 
.SS "\fBglobus_result_t\fP globus_callback_space_attr_destroy (\fBglobus_callback_space_attr_t\fPattr)"

.PP
Destroy a space attr\&. 
.PP
\fBParameters:\fP
.RS 4
\fIattr\fP attr to destroy, previously initialized with \fBglobus_callback_space_attr_init()\fP
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL attr
.IP "\(bu" 2
GLOBUS_SUCCESS
.PP
.RE
.PP
\fBSee also:\fP
.RS 4
\fBglobus_callback_space_attr_init()\fP 
.RE
.PP

.SS "\fBglobus_result_t\fP globus_callback_space_attr_get_behavior (\fBglobus_callback_space_attr_t\fPattr, \fBglobus_callback_space_behavior_t\fP *behavior)"

.PP
Get the behavior associated with an attr\&. Note: for a non-threaded build, this will always pass back a behavior == GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE\&.
.PP
\fBParameters:\fP
.RS 4
\fIattr\fP attr on which to query behavior
.br
\fIbehavior\fP storage for the behavior
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
.IP "\(bu" 2
GLOBUS_SUCCESS 
.PP
.RE
.PP

.SS "\fBglobus_result_t\fP globus_callback_space_attr_init (\fBglobus_callback_space_attr_t\fP *attr)"

.PP
Initialize a space attr\&. Currently, the only attr to set is the behavior\&. The default behavior associated with this attr is GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE
.PP
\fBParameters:\fP
.RS 4
\fIattr\fP storage for the intialized attr\&. Must be destroyed with \fBglobus_callback_space_attr_destroy()\fP
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL attr
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC
.IP "\(bu" 2
GLOBUS_SUCCESS 
.PP
.RE
.PP

.SS "\fBglobus_result_t\fP globus_callback_space_attr_set_behavior (\fBglobus_callback_space_attr_t\fPattr, \fBglobus_callback_space_behavior_t\fPbehavior)"

.PP
Set the behavior of a space\&. 
.PP
\fBParameters:\fP
.RS 4
\fIattr\fP attr to associate behavior with
.br
\fIbehavior\fP desired behavior
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT
.IP "\(bu" 2
GLOBUS_SUCCESS
.PP
.RE
.PP
\fBSee also:\fP
.RS 4
\fBglobus_callback_space_behavior_t\fP 
.RE
.PP

.SS "\fBglobus_result_t\fP globus_callback_space_destroy (\fBglobus_callback_space_t\fPspace)"

.PP
Destroy a reference to a user space\&. This will destroy a reference to a previously initialized space\&. Space will not actually be destroyed until all callbacks registered with this space have been run and unregistered (if the user has a handle to that callback) AND all references (from \fBglobus_callback_space_reference()\fP) have been destroyed\&.
.PP
\fBParameters:\fP
.RS 4
\fIspace\fP space to destroy, previously initialized by \fBglobus_callback_space_init()\fP or referenced with \fBglobus_callback_space_reference()\fP
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_SPACE
.IP "\(bu" 2
GLOBUS_SUCCESS
.PP
.RE
.PP
\fBSee also:\fP
.RS 4
\fBglobus_callback_space_init()\fP 
.PP
\fBglobus_callback_space_reference()\fP 
.RE
.PP

.SS "\fBglobus_result_t\fP globus_callback_space_get (\fBglobus_callback_space_t\fP *space)"

.PP
Retrieve the space of a currently running callback\&. 
.PP
\fBParameters:\fP
.RS 4
\fIspace\fP storage for the handle to the space currently running
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL space
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_NO_ACTIVE_CALLBACK
.IP "\(bu" 2
GLOBUS_SUCCESS 
.PP
.RE
.PP

.SS "int globus_callback_space_get_depth (\fBglobus_callback_space_t\fPspace)"

.PP
Retrieve the current nesting level of a space\&. 
.PP
\fBParameters:\fP
.RS 4
\fIspace\fP The space to query\&.
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
the current nesting level
.IP "\(bu" 2
-1 on invalid space 
.PP
.RE
.PP

.SS "\fBglobus_result_t\fP globus_callback_space_init (\fBglobus_callback_space_t\fP *space, \fBglobus_callback_space_attr_t\fPattr)"

.PP
Initialize a user space\&. This creates a user space\&.
.PP
\fBParameters:\fP
.RS 4
\fIspace\fP storage for the initialized space handle\&. This must be destroyed with \fBglobus_callback_space_destroy()\fP
.br
\fIattr\fP a space attr descibing desired behaviors\&. If GLOBUS_NULL, the default behavior of GLOBUS_CALLBACK_SPACE_BEHAVIOR_SINGLE is assumed\&. This attr is copied into the space, so it is acceptable to destroy the attr as soon as it is no longer needed
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_ARGUMENT on NULL space
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_MEMORY_ALLOC
.IP "\(bu" 2
GLOBUS_SUCCESS
.PP
.RE
.PP
\fBSee also:\fP
.RS 4
\fBglobus_condattr_setspace()\fP 
.PP
globus_io_attr_set_callback_space() 
.RE
.PP

.SS "\fBglobus_bool_t\fP globus_callback_space_is_single (\fBglobus_callback_space_t\fPspace)"

.PP
See if the specified space is a single threaded behavior space\&. 
.PP
\fBParameters:\fP
.RS 4
\fIspace\fP the space to query
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_TRUE if space's behavior is _BEHAVIOR_SINGLE
.IP "\(bu" 2
GLOBUS_FALSE otherwise 
.PP
.RE
.PP

.SS "\fBglobus_result_t\fP globus_callback_space_reference (\fBglobus_callback_space_t\fPspace)"

.PP
Take a reference to a space\&. A library which has been 'given' a space to provide callbacks on would use this to take a reference on the user's space\&. This prevents mayhem should a user destroy a space before the library is done with it\&. This reference should be destroyed with \fBglobus_callback_space_destroy()\fP (think dup())
.PP
\fBParameters:\fP
.RS 4
\fIspace\fP space to reference
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
GLOBUS_CALLBACK_ERROR_INVALID_SPACE
.IP "\(bu" 2
GLOBUS_SUCCESS 
.PP
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for globus_common from the source code\&.