SolarCapture C Bindings User Guide  SF-115721-CD
Draft 2A
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
session.h File Reference

sc_session: A set of threads and other objects. More...

Data Structures

struct  sc_session_error
 A SolarCapture session error object returned by sc_session_error_get. More...
 

Functions

int sc_session_alloc (struct sc_session **scs_out, const struct sc_attr *attr)
 Allocate a SolarCapture session. More...
 
int sc_session_destroy (struct sc_session *scs)
 Destroy a SolarCapture session. More...
 
int sc_session_prepare (struct sc_session *scs)
 Prepare a SolarCapture session. More...
 
int sc_session_go (struct sc_session *scs)
 Start a SolarCapture session. More...
 
int sc_session_run (struct sc_session *scs, int *exit_code_out)
 Start a SolarCapture session and wait until it stops. More...
 
int sc_session_pause (struct sc_session *scs)
 Pause a SolarCapture session. More...
 
int sc_session_stop (struct sc_session *scs, int exit_code)
 Stop a SolarCapture session, causing sc_session_run() to return. More...
 
struct sc_session_errorsc_session_error_get (struct sc_session *scs)
 Returns an error from a SolarCapture session. More...
 
void sc_session_error_free (struct sc_session *scs, struct sc_session_error *err)
 Frees an error object. More...
 

Detailed Description

sc_session: A set of threads and other objects.

Function Documentation

int sc_session_alloc ( struct sc_session **  scs_out,
const struct sc_attr attr 
)

Allocate a SolarCapture session.

Parameters
scs_outThe allocated session object is returned here
attrAttributes for the new session
Returns
0 on success, or a negative error code.

This function allocates a SolarCapture session.

A session comprises a set of threads, VIs, nodes and/or other SolarCapture objects.

int sc_session_destroy ( struct sc_session *  scs)

Destroy a SolarCapture session.

Parameters
scsThe session

This call stops the session and frees all of the associated resources, including threads, nodes etc.

void sc_session_error_free ( struct sc_session *  scs,
struct sc_session_error err 
)

Frees an error object.

Parameters
scsThe session
errThe error

Frees a sc_session_error pointer returned by sc_session_error_get.

struct sc_session_error* sc_session_error_get ( struct sc_session *  scs)

Returns an error from a SolarCapture session.

Parameters
scsThe session
Returns
A pointer to a sc_session_error struct representing the error encountered by session scs. The caller should pass the pointer to sc_session_error_free once once done with it.
If no error has occurred, this function returns NULL.
int sc_session_go ( struct sc_session *  scs)

Start a SolarCapture session.

Parameters
scsThe session
Returns
0 on success, or a negative error code.

Prepare the session scs (if necessary) and start the managed threads. This is usually called just once, after allocating resources. It can also be called after sc_session_pause() to restart a paused session.

int sc_session_pause ( struct sc_session *  scs)

Pause a SolarCapture session.

Parameters
scsThe session
Returns
0 on success, or a negative error code.

Pause the threads managed by session scs.

This function must not be invoked by a SolarCapture managed thread.

int sc_session_prepare ( struct sc_session *  scs)

Prepare a SolarCapture session.

Parameters
scsThe session
Returns
0 on success, or a negative error code.

Prepare the session scs. This step includes finalising resource allocations, preparing nodes, and starting packet capture. Managed threads are started in the "paused" state.

Note that although packet capture is started, you may get packet loss if the threads managing 'sc_vi's are not started soon afterwards.

Call sc_session_go() to start the managed threads and begin packet processing.

int sc_session_run ( struct sc_session *  scs,
int *  exit_code_out 
)

Start a SolarCapture session and wait until it stops.

Parameters
scsThe session
exit_code_outExit code from sc_session_stop() returned here
Returns
0 on success, or a negative error code.

This function calls sc_session_go(), and then waits until sc_session_stop() is called. The exit code passed to sc_session_stop() is returned via p_exit_code (which can be NULL if the exit code is not wanted).

Calling sc_session_run() changes the default action of the sc_exit node so that it calls sc_session_stop() when the exit condition is met.

int sc_session_stop ( struct sc_session *  scs,
int  exit_code 
)

Stop a SolarCapture session, causing sc_session_run() to return.

Parameters
scsThe session
exit_codeExit code passed to sc_session_run()
Returns
>= 0 on success, or a negative error code.

This function calls sc_session_pause(), and also causes sc_session_run() to stop waiting and return exit_code.

This function can be invoked in an application thread or a SolarCapture managed thread. In the latter case it will return immediately and the work will be deferred to a background thread.