GOLF(2gg)

NAME
call-remote - (distributed-computing)

PURPOSE
Make a remote service call.

SYNTAX

        call-remote <service> [ ,... ]   \
            [ status <status> ]  \
            [ started <started> ] \
            [ finished-okay <finished okay> ]

DESCRIPTION
call-remote will make service call(s) as described in a single <service> or a list of <service>s. Unless only a single <service> is specified, each call will execute in parallel with others (as multiple threads). call-remote finishes when all <service> calls do. Each <service> must have beed created with new-remote.

A <service> call is made to a remote service. "Remote service" means a process accepting requests that is not the same process executing call-remote; it may be running on the same or a different computer, or it may be a different process started by the very same application.

- Multiple service calls in parallel

Executing multiple <service> calls in parallel is possible by specifying a list of <service>s separated by a comma.

There is no limit on how many <service>s you can call at the same time; it is limited only by the underlying Operating System resources, such as threads/processes and sockets.

- Call status

<status> number (in "status" clause) will be GG_OKAY if all <service> calls have each returned GG_OKAY; this means all have started and all have finished with a valid message from the service; or GG_ERR_FAILED if at least one did not (for example if the service could not be contacted, if there was a network error etc.); or GG_ERR_MEMORY if out of memory; or GG_ERR_TOO_MANY if there is too many calls (more than 1,000,000).

Note that GG_OKAY does not mean that the reply is considered a success in any logical sense; only that the request was made and a reply was received according to the service protocol.

- Request(s) status

Note that the actual application status for each <service>, as well as data returned and any application errors can be obtained via "exit-status", "data" and "error" clauses of read-remote statement, respectively.

- Request(s) duration

call-remote will wait for all <service> requests to finish. For that reason, it is a good idea to specify "timeout" clause in new-remote for each <service> used, in order to limit the time you would wait. Use read-remote to detect a timeout, in which case "exit-status" clause would produce GG_CLI_ERR_TIMEOUT.

- How many calls started and finished

<started> (in "started" clause) will be the number of service calls that have started. <finished okay> (in "finished-okay" clause) is the number of calls that have finished with return value of GG_OKAY as described above. By using <status>, <started> and <finished okay> you may surmise whether the results of call-remote meet your expectations.

- Performance, security

call-remote is faster than call-web because it does not use HTTP protocol; rather it only uses small and binary protocol, which is extremenly fast, especially when using Unix sockets on the same machine (see new-remote). Note that the binary protocol does not have any inherent security built-in; that is part of the reason why it is fast. As such, it is very well suited for remote service calls on the same machine or between networked machines on a secure network.

EXAMPLES
This example will connect to local Unix socket file "/var/lib/gg/app_name/sock/sock" (a Golf application named "app_name"), and make a request named "server" (i.e. it will be processed by source code file "server.golf") with URL path of "/op=add/key=2" (meaning with input parameters "op=add" and "key=2"). Then, service reply is read and displayed.

        // Create single call
        new-remote srv location "/var/lib/gg/app_name/sock/sock" \
            method "GET" app-path "/app_name" request-path "/server" \
            url-params "/op=add/key=2"
        // Call single service call
        call-remote srv finished-okay sfok
        // Get results of a remote service call
        read-remote srv data rdata
        // Display results
        @Data from service is <<print-out rdata>>

If you are connecting to a service via TCP (and not with a Unix socket like in the example above), the "location" clause in new-remote might be:

        new-remote srv location "192.168.0.28:2400" \
            method "GET" app-path "/app_name" request-path "/server" \
            url-params "/op=add/key=2"

In this case, you are connecting to another service (running on IP "192.168.0.28") on port 2400. See mgrg on how to start a service that listens on a TCP port. You would likely use TCP connectivity only if a service you're connecting to is on a different computer.

See also new-remote.

SEE ALSO
 Distributed computing

call-remote new-remote read-remote run-remote See all documentation