Main Page Class Hierarchy Compound List Compound Members Session Class Reference
An object to enable the client to manage its workload. More...
Public Types
enum SessionCloseFlags { DestroyOnClose = SCF_DESTROY_ON_CLOSE, DetachOnClose = SCF_DETACH_ON_CLOSE } enum SessionFlags {
SendSync = SF_SEND_SYNC, SendOverlapped = SF_SEND_OVERLAPPED, ReceiveSync = SF_RECEIVE_SYNC, ReceiveAsync = SF_RECEIVE_ASYNC,
FetchResultsDirectly = SF_FETCH_RESULTS_DIRECTLY, AliasSync = SendSync | ReceiveSync, AliasPartialAsync = SendSync | ReceiveAsync
}enum DataCompressionFlags { BestSpeed = DCF_BEST_SPEED, BetterSize = DCF_MEDIAN_LEVEL } enum DirectDataTransferFlags { IncludeCommonDataAndUpdates = DDTF_INCLUDE_COMMON_DATA_AND_UPDATES, ExcludeInputData = DDTF_EXCLUDE_INPUT_DATA, ExcludeOutputData = DDTF_EXCLUDE_OUTPUT_DATA } Public Methods
const char * getId (void) const throw (SoamException) Get an ID of a Session. TaskInputHandle * sendTaskInput (Message *taskInput, bool hasPriority=false) throw (SoamException) Send task inputs. TaskInputHandle * sendTaskInput (TaskSubmissionAttributes &attributes) throw (SoamException) Send message to SOAM. EnumItems * fetchTaskOutput (SoamULong countMax, SoamLong timeoutInSeconds=globalConst(TimeoutInfinite)) throw (SoamException) Get response from SOAM. EnumItems * fetchTaskOutput (TaskOutputFilter &filter, SoamInt32 timeoutInSeconds=globalConst(TimeoutInfinite)) throw (SoamException) Retrieves the task outputs that match the specified filter. void close (unsigned long closeFlags=DestroyOnClose) throw (SoamException) Close the session. void update (SessionUpdateAttributes &attr) throw (SoamException) Updates the session with the provided attributes. void updatePriority (const SoamInt32 priority) throw (SoamException) Updates the session with the provided priority. Friends
class Connection Detailed Description
An object to enable the client to manage its workload.Created by the connection object to enable the client to manage its workload and can be considered as a conduit for tasks being submitted to the service instances.
NOTE: It is always best to access a pointer to this type of object through the appropriate smart pointer type instead of using a raw pointer.
- See also:
- SessionPtr , Connection
Member Enumeration Documentation
enum SessionCloseFlags
Session::SessionCloseFlags Flags used to indicate how the session is to be closed.
- Enumeration values:
DestroyOnClose This informs the API that the client no longer intends to use the session. This is the default behaviour if this parameter is ignored. Closing the session in this way will result in the session being terminated within the middleware. All outstanding results will be discarded. DetachOnClose This informs the API that the client no longer intends to use the session locally, but intends for the workload to continue running within the middleware. In effect this session will become within the Middleware and become available for any client wishing to access it. A client must call Connection::openSession to gain access to this session once it has been closed in this manner.
enum SessionFlags
Session::SessionFlags Falgs used to inform the API of any extended behavior to associate with the session.
- Enumeration values:
SendSync This informs the API that the client requires the submission of input to be in a "synchonous" manner. This means that the call to Session::sendTaskInput() will block the client's thread until it recieves a confirmation from the middleware that the input has been safely received. This is the default sending behaviour (if no "Send" flag is specified). SendOverlapped This informs the API that the client requires the submission of input to be in an "overlapped" manner. This means that the call to Session::sendTaskInput() will *not* block the client's thread. The client is then free to get the status of the submission of the input at a later time from the returned TaskInputHandle object. ReceiveSync This informs the API that the client is expecting that the result of its computation will be returned in a synchronous manner. This means that the client will use the Session::fetchTaskOutput() method to retrieve the output. ReceiveAsync This informs the API that the client is expecting that the result of its computation will be returned in an asynchronous manner. This means that the client is expected to provide a SessionCallback object which will be invoked each time a result is available. FetchResultsDirectly This informs the API that the client expects that results will only be returned to the middleware upon the explicit request of the client. By default the API will cache results as they are returned from the Symphony Session Manager to boost the performance of results retrieval. Developers are strongly encouraged to fetch their results in small increments once this flag is enabled to reduce any impact to the overall performance of the Middleware during the handling of the fetch request. Note that this flag is intended for usage with the "ReceiveSync" flag.
e.g. you may create a session which will retrieve results synchronously as follows;
// Set up session creation attributes
SessionCreationAttributes attributes;
attributes.setSessionName("mySession");
attributes.setSessionType("ShortRunningTasks");
attributes.setSessionFlags(ReceiveSync | FetchResultsDirectly);
// Now create session
SessionPtr sesPtr = conPtr->createSession(attributes);
See the Session::fetchTaskOutput() method for more details.AliasSync This alias can be used instead of the following combination "SendSync | ReceiveSync" AliasPartialAsync This alias can be used instead of the following combination "SendSync | ReceiveAsync"
enum DataCompressionFlags
Session::DataCompressionFlags Data compression flags are used to modify the behavior of the data compression feature.
- Enumeration values:
enum DirectDataTransferFlags
Session::DirectDataTransferFlags Direct Data Transfer flags are used to modify the behavior of the Direct Data Transfer feature.
- Enumeration values:
Member Function Documentation
const char* getId ( void ) const throw (SoamException)
Get an ID of a Session.
Retrieve the ID associated with the session. This ID can be used to allow another client to attach to this session.
- Returns:
- a Session ID.
- Exceptions:
SoamException
TaskInputHandle* sendTaskInput ( Message * taskInput, bool hasPriority = false ) throw (SoamException)
Send task inputs.
This method will deliver the provided input message to the system. For synchronous (created with flag Session::Sync) and partially asynchronous (created with flag Session::PartialAsynSF_PARTIAL_ASYNC) session, this method will wait for acknowledgement from the Symphony Session Manager that the message been safely accepted and will be processed as soon as possible in which case a task ID will be returned. For fully asynchronous mode the acknowledgement will return on the callback and the method call will not be blocked.
- Deprecated:
- This method was deprecated in Symphony 3.2, use
TaskInputHandle* Session::sendTaskInput(const TaskSubmissionAttributes& attributes
instead.IMPORTANT NOTE:
The sendTaskInput(...) method always returns a TaskInputHandle object. This means that even if the developer has no intention of using the returned object, the returned object should always be assigned to a smartpointer to ensure that there is no memory leaked from the client. e.g.
// send it
TaskInputHandlePtr input = sesPtr->sendTaskInput(msg);
- Parameters:
taskInput [IN] - a message to be sent to SOAM. hasPriority [IN] - this is an optional parameter which indicates to the Middleware that the message being submitted should take priority in the current session. This means that it will be used to create a task which will be placed at the front of the dispatch queue. The default value for this parameter is false if not specified in which case the newly created task will be placed at the rear of the dispatch queue.
- Returns:
- a pointer of a TaskInputHandle object.
- Exceptions:
SoamException
- See also:
- Connection::createSession , TaskInputHandle
TaskInputHandle* sendTaskInput ( TaskSubmissionAttributes & attributes ) throw (SoamException)
Send message to SOAM.
This method will deliver the provided input message to the system. For synchronous (created with flag SF_SYNC) and partially asynchronous (created with flag SF_PARTIAL_ASYNC) session, this method will wait for acknowledgement from the Symphony Session Manager. For overlapped sending of results (SF_SEND_OVERLAPPED) this method will not block and the the submission state of the message can be obtained from the returned TaskInputHandle object. Once the message been safely accepted by the Middleware it will be processed as soon as possible in which case a task ID will be returned. This task ID can be obtained from the TaskInputHandle as well.
IMPORTANT NOTE:
The sendTaskInput(...) method always returns a TaskInputHandle object. This means that even if the developer has no intention of using the returned object, the returned object should always be assigned to a smartpointer to ensure that there is no memory leaked from the client. e.g.
// send it
TaskInputHandlePtr input = sesPtr->sendTaskInput(attrTask);
- Parameters:
attributes [IN] - The attributes to apply to the task upon creation.
- Returns:
- a pointer of a TaskInputHandle object.
- Exceptions:
SoamException
- See also:
- Connection::createSession , TaskInputHandle
EnumItems* fetchTaskOutput ( SoamULong countMax, SoamLong timeoutInSeconds = globalConst(TimeoutInfinite) ) throw (SoamException)
Get response from SOAM.
Attempts to retrieve the number of specified output messages currently ready and waiting that were produced by the service instance. The replies will be presented as an enumeration.If a timeout within the range of 0 - 31556926 seconds is specified, then if there is less than the specified amount of output messages ready when the timeout interval is exceeded, the method will return with a subset of the requested items. This subset can be 0 to countMax.
IMPORTANT NOTE:
If your session was created using theFetchResultsDirectly
flag then the timeout will be ignored and the call will return with 0 - N items. The number of items returned will depend on whatever results are availble in the Symphony Session Manager at the time of the call. Also, when theFetchResultsDirectly
flag is used, developers are strongly encouraged to fetch their results in smaller increments to reduce any impact to the overall performance of the Middleware during the handling of the fetch request.
- Parameters:
countMax [IN] - maximum output items to be returned by SOAM. timeoutInSeconds [IN] - how much time should pass before giving up on trying to fulfill the request. The maximum number of seconds allowed is 31556926 seconds.
- Returns:
- a pointer to an EnumItems object.
- Exceptions:
SoamException
- See also:
- EnumItems
EnumItems* fetchTaskOutput ( TaskOutputFilter & filter, SoamInt32 timeoutInSeconds = globalConst(TimeoutInfinite) ) throw (SoamException)
Retrieves the task outputs that match the specified filter.
If a timeout of 0 seconds is specified, this method will return the results that are available at this moment. This result set can contain 0 or more items. Any matched tasks in the resulting EnumItems will be removed from the filter once this method call returns.
NOTE:
This method is for use only if your session is created with theFetchResultsDirectly
andReceiveSync
session flags.
- Parameters:
filter [IN] - Describes which task outputs to retrieve. timeoutInSeconds [IN] - Time to wait before giving up on trying to fulfill the request. Valid values are: Default value is globalConst(TimeoutInfinite).
- globalConst(TimeoutInfinite) : Block until all of the specified task outputs are ready.
- 0 : Return with the specified task outputs that are available right now.
- Returns:
- a pointer to an EnumItems object.
- Exceptions:
SoamException
- See also:
- EnumItems
- See also:
- TaskIdFilter
void close ( unsigned long closeFlags = DestroyOnClose ) throw (SoamException)
Close the session.
Once a session is closed no further operations can be performed on the session within the client.
** NOTE : Never call close(...) during the execution of a callback method. This will result in a deadlock.
- Parameters:
closeFlags [IN] - This flag allows the client to specify explicitly which Session::SessionCloseFlag to use when closing the session.
- Exceptions:
SoamException
- See also:
- Connection::openSession , Session::SessionCloseFlags
void update ( SessionUpdateAttributes & attr ) throw (SoamException)
Updates the session with the provided attributes.
- Parameters:
attr [IN] The attributes to apply to the session upon update.
- Exceptions:
SoamException
- See also:
- SessionUpdateAttributes
void updatePriority ( const SoamInt32 priority ) throw (SoamException)
Updates the session with the provided priority.
Note: The session priority can be any number between 1 and 10,000 (highest priority) inclusive.
- Parameters:
priority [IN] The priority to apply to the session upon update.
- Exceptions:
SoamException
Date Modified: 11 Nov 2009
Platform Support: support@platform.com
Platform Information Development: doc@platform.com
Platform Computing. Accelerating Intelligence(TM).
Copyright © 2001-2009 Platform Computing Corporation. All rights reserved.