Service/Sources/EDOInvocationMessage.h

//
// Copyright 2018 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

#import "Service/Sources/EDOServiceRequest.h"

#import "Service/Sources/EDOObject+Private.h"
#import "Service/Sources/EDORemoteException.h"

NS_ASSUME_NONNULL_BEGIN

@class EDOHostPort;
@class EDOHostService;
@class EDOParameter;
typedef EDOParameter EDOBoxedValueType;

/** The invocation request to make a remote invocation. */
@interface EDOInvocationRequest : EDOServiceRequest

- (instancetype)init NS_UNAVAILABLE;

/**
 * Creates an invocation request.
 *
 * @param target        The remote target's plain address. The caller needs to make sure the
 *                      address is valid.
 * @param selector      The selector that is sent to the @c target. @c nil if the target is a
 *                      block.
 * @param arguments     The array of arguments to send.
 * @param hostPort      The host port the request is sent to.
 * @param returnByValue @c YES if the invocation should return the object by value instead of by
 *                      reference (for value-types that are already return-by-value by default,
 *                      this will be a no-op).
 */
+ (instancetype)requestWithTarget:(EDOPointerType)target
                         selector:(SEL _Nullable)selector
                        arguments:(NSArray *)arguments
                         hostPort:(EDOHostPort *)hostPort
                    returnByValue:(BOOL)returnByValue;

/**
 * Creates an invocation request from an @c invocation on an EDOObject.
 *
 * @param invocation    The invocation.
 * @param target        The EDOObject.
 * @param selector      The selector to be sent. When this is nil, the case for a block invocation,
 *                      the index of the actual arguments starts at 1; otherwise the case for an
 *                      object invocation, it starts at 2.
 * @param returnByValue @c YES if the invocation should return the object by value instead of by
 *                      reference.
 * @param service       The host service used to wrap the arguments in the @c invocation if any.
 *
 * @return An instance of EDOInvocationRequest.
 */
+ (instancetype)requestWithInvocation:(NSInvocation *)invocation
                               target:(EDOObject *)target
                             selector:(SEL _Nullable)selector
                        returnByValue:(BOOL)returnByValue
                              service:(EDOHostService *)service;

@end

/** The invocation response for the remote invocation. */
@interface EDOInvocationResponse : EDOServiceResponse

/** The exception if thrown remotely. */
@property(nonatomic, readonly, nullable) EDORemoteException *exception;
/** The boxed return value. */
@property(nonatomic, readonly, nullable) EDOBoxedValueType *returnValue;
/** The boxed values for out parameter. */
@property(nonatomic, readonly, nullable) NSArray<EDOBoxedValueType *> *outValues;
/**
 * Whether the returned object is retained.
 *
 * With ARC, -retain, -release, and -autorelease, or equivalent methods will be inserted at
 * compile time to ensure the correct ownership, according to Objective-C memory conventions,
 * however it doesn't guarantee that the retain count will always balance, for example,
 * NS_RETURNS_RETAINED will instruct ARC to explicitly transfer the ownership without adding
 * an extra -retain. ARC reserves the right to remove any -retain/-release if safe in the context
 * of a source file. As eDO builds the remote invocation using @c NSInvocation, this context will
 * be lost and ARC treats the memory as what @c NSInvocation states, that is, the annotation gets
 * lost and all the returns are already balanced. However the returned object will still be
 * retained if the method family is one of +alloc, +new, -mutableCopy, or -copy. ARC will balance
 * this by inserting an extra release on the caller, and the object returned will have an extra
 * retain count, thus we need to:
 *  1) insert an extra retain on the caller;
 *  2) insert an extra release on the receiver,
 * to ensure that the retain count is balanced.
 *
 * For more details see
 * [ARC
 * documentation](https://developer.apple.com/library/archive/releasenotes/ObjectiveC/RN-TransitioningToARC/Introduction/Introduction.html),
 * [the method
 * families](http://clang.llvm.org/docs/AutomaticReferenceCounting.html#method-families), and
 * [retained return
 * values](https://clang.llvm.org/docs/AutomaticReferenceCounting.html#retained-return-values).
 */
@property(nonatomic, readonly) BOOL returnRetained;

- (instancetype)init NS_UNAVAILABLE;

@end

NS_ASSUME_NONNULL_END