Visit Platform at http://www.platform.com

Main Page   Class Hierarchy   Compound List   Compound Members  

Session Class Reference

An object to enable the client to manage its workload. More...

List of all members.


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.

TaskInputHandlesendTaskInput (Message *taskInput, bool hasPriority=false) throw (SoamException)
 Send task inputs.

TaskInputHandlesendTaskInput (TaskSubmissionAttributes &attributes) throw (SoamException)
 Send message to SOAM.

EnumItemsfetchTaskOutput (SoamULong countMax, SoamLong timeoutInSeconds=globalConst(TimeoutInfinite)) throw (SoamException)
 Get response from SOAM.

EnumItemsfetchTaskOutput (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.


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:
BestSpeed  This informs the API to use the fastest compression method to compress the data. The use of BestSpeed will result in less compression than BetterSize (i.e. resulting data might be larger), however, data may be compressed in a noticeably shorter time.
BetterSize  This informs the API to use the median level compression method to compress the data. The use of BetterSize will result in slower compression times than BestSpeed, however, data may experience greater compression (i.e. resulting data might be noticeably smaller).

enum DirectDataTransferFlags
 

Session::DirectDataTransferFlags Direct Data Transfer flags are used to modify the behavior of the Direct Data Transfer feature.

Enumeration values:
IncludeCommonDataAndUpdates  This informs the API to include CDU data when it is transferring the data directly. This flag is not set by default.
ExcludeInputData  This informs the API to exclude input data when it is transferring the data directly. This flag is not set by default.
ExcludeOutputData  This informs the API to exclude output data when it is transferring the data directly. This flag is not set by default.

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.

Deprecated:
This method was deprecated in Symphony 3.2, use
TaskInputHandle* Session::sendTaskInput(const TaskSubmissionAttributes& attributes instead.
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.

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 the FetchResultsDirectly 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 the FetchResultsDirectly 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 the FetchResultsDirectly and ReceiveSync 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:
  • globalConst(TimeoutInfinite) : Block until all of the specified task outputs are ready.
  • 0 : Return with the specified task outputs that are available right now.
Default value is globalConst(TimeoutInfinite).
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


     
Date Modified: 3 Nov 2008
Platform Support: support@platform.com
Platform Information Development: doc@platform.com

Platform Computing. Accelerating Intelligence(TM).
Copyright © 2001-2008 Platform Computing Corporation. All rights reserved.